diff --git a/admindoc.md b/admindoc.md index 9194c8a4..5a7e9d82 100644 --- a/admindoc.md +++ b/admindoc.md @@ -44,7 +44,7 @@ * [Hide services with Tor](/torhiddenservice) * [A discussion about the advantages of using a VPN](/vpn_advantage) * [(old) Jessie->Stretch migration procedure](jessie_stretch_migration) -* [Troubleshooting guide](/troubleshooting_guide) +* Troubleshooting * [Changing the administration password](/change_admin_password) * [Recover access to your server](/noaccess) * [Unban IPs in iptables/fail2ban](/fail2ban) diff --git a/admindoc_de.md b/admindoc_de.md index f9c0b256..ee77f645 100644 --- a/admindoc_de.md +++ b/admindoc_de.md @@ -40,6 +40,6 @@ * [Für externen Speicher hinzu](/external_storage) * [Migriere E-Mails zu Yunohost](/email_migration) * [Verstecke Services mit Tor](/torhiddenservice) -* [Hinweise zur Fehlersuche](/troubleshooting_guide) +* Hinweise zur Fehlersuche * [Entsperren von IPs in fail2ban](/fail2ban) * [Administrator-Passwort ändern](/change_admin_password) diff --git a/admindoc_fr.md b/admindoc_fr.md index 6dc54324..9b4c723f 100644 --- a/admindoc_fr.md +++ b/admindoc_fr.md @@ -55,7 +55,7 @@ * [Utilisation de certificats autres que Let's Encrypt](/certificate_custom) * [Une discussion sur les avantages d'utiliser un VPN](/vpn_advantage) * [(vieux) Procedure de Migration Jessie->Stretch](jessie_stretch_migration) -* [Guide de dépannage](/troubleshooting_guide) +* Dépannage * [Changer le mot de passe d’administration](/change_admin_password) * [Récupérer l'accès à son serveur](/noaccess) * [Débannir une IP dans Fail2ban/IPtables](/fail2ban) diff --git a/troubleshooting_guide.md b/troubleshooting_guide.md deleted file mode 100644 index f1d85a0b..00000000 --- a/troubleshooting_guide.md +++ /dev/null @@ -1,345 +0,0 @@ -# YunoHost troubleshooting guide - -You can consider this as some kind of administrator guide for troubleshooting or what to check when there is something wrong with your YunoHost server. It's not a step by step guide to make your YunoHost work but more of a list of things to check to help diagnose the issue you may have. This can also be useful for debug when packaging a new application or trying to understand YunoHost architecture. - -## General notes -### Do not break YunoHost -Best way to troubleshoot is to not have to troubleshoot because you have tested everything before deploying it on your server. -This means that everytime you want to try a new thing (non-official app, new specific config, package an app...), you should try it on a development or testing instance, *not* on your production server. For this, you can [set up a virtualbox](install_on_virtualbox), or for instance a [DigitalOcean droplet](install_on_vps) for 1 cent/hour. - -Also: https://wiki.debian.org/DontBreakDebian - -### Do not install bad quality apps - -Even if it can be tempting to install every [apps](/apps), be careful to their quality level as a bad quality app can ultimately break your server. If you absolutely wish to install such an app, at least try to do it on a test server or check if issues has been posted to this app's Github repository or on the [forum](http://forum.yunohost.org/). - -### Check the official documentation -Answer to your question may be already in [the documentation](/docs). - -### Check the command line help -Learn how to use the [YunoHost commands](/commandline) like a pro. - -## Upgrade -Problems often occur after an upgrade. After a YunoHost upgrade you may want to [update your apps](/app_update). - -**Check if some processes are using old libraries** - -You are probably familiar with: -```bash -$ apt update && apt dist-upgrade -``` -Most of the time it's enough. But in some cases it's possible that some process are still using old versions of upgraded files (such as libraries), that can cause bug. In rare cases that can lead to security concern (ex: upgrade OpenSSL because of a security bug, Nginx will continue to use the version it has in memory). The utility Checkrestart will help you to find and restart them. - -```bash -$ apt install debian-goodies -$ checkrestart -Found 0 processes using old versions of upgraded files -``` -If some process are running with old librairies versions checkrestart will tell you and propose you a way to restart them. In some cases checkrestart can't find a way to restart them. - - - -Easier way is to reboot if you can. - -You can also use [this script](https://github.com/octopuce/octopuce-goodies/blob/master/checkrestart/checkrestart.octopuce) to automaticaly restart some services if needed. More info in French [here](https://www.octopuce.fr/checkrestart-outil-pratique-de-debian-goodies-et-version-octopuce/). - -**Force an upgrade on a community app** - -/!\ Always check if there is a upgrade script and read it if you can /!\ -```bash -$ yunohost app upgrade -Warning: You must provide an URL to upgrade your custom app app_name -Error: No app to upgrade -$ yunohost app upgrade -u https://github.com/user/someapp_ynh app_name -``` - -## Services -YunoHost uses a bunch of software to accomplish its purpose. Most of theses software are registered as service in Debian. [More info](/whatsyunohost). - -### Check services status -When something doesn't work on your YunoHost, one of the first things to do is to check that all services used by YunoHost are running. -YunoHost include a helper to see the status of all services used by YunoHost: -```bash -$ yunohost service status -``` - -Sample result: - - - -All services should be enabled and running. Except glances (optional). If some are not, try to restart them. Here is a short description of what they do: - -- **Amavis**: anti-spam/virus/malwares, used when receiving email -- **Avahi-daemon**: system which facilitates service discovery on a local network via DNS -- **DNSmasq**: DNS server, you are not forced to use it -- **Dovecot**: IMAP email server, used to receive email -- **Glances**: optional, used by web administration to display server status -- **Metronome**: XMPP instant messaging server, used by Jappix and some external client -- **MySQL**: database, used by some app -- **Nginx**: web server, used by all web app -- **php5-fpm**: PHP service, used by all app written in PHP -- **Postfix**: SMTP email server, used to send email -- **Postgrey**: greylisting policy server, if you use YunoHost email, you should [learn more about greylisting](http://en.wikipedia.org/wiki/Greylisting) -- **Slapd**: LDAP server, used for authentification (SSO and apps) -- [**SSH**](/ssh): Secure Shell -- [**SSOwat**](https://github.com/Kloadut/SSOwat/): an simple sign-on -- **YunoHost-API**: YunoHost web administration - -Others services installed by applications can also be present. For instance, `seafile-serve` which serves Seafile app and `uwsgi` which serve Python apps such as Searx. - -##### Start or stop a service which is registered with YunoHost: - -```bash -$ yunohost service start -$ yunohost service stop -``` -You can also use the generic Debian command: -```bash -$ systemctl start/stop/restart/reload -``` -After a launch attempt, always check that the service is running. - -### Logs -If a service won't start you have to check the logs to see what's wrong. There is no generic way for services to store their logs, but there are mainly stocked in: `/var/log/` - -Here are the some useful logs files for YunoHost: - -##### auth.log -Contains connections or attempt of connection to your server. It includes every web, ssh, cron job connection. It also stockes all the failed (hopefully) attempts to connect by a potential intruders connections. - -##### fail2ban.log -When someone tries to connect to your server and fails multiple times, Fail2ban bans the IP address to avoid bruteforce and (D)DOS attacks. Here you can see if some IP have been banned. - -##### mail.err, mail.info, mail.log, mail.warn -These are Postfix (the mail server) logs, check theses if you have issues with email. - -##### metronome/metronome.err, metronome/metronome.log -XMPP chat server logs. - -##### mysql.err, mysql.log, mysql/error.log -MySQL database logs, these should be empty unless you have trouble with MySQL. - -##### php7.0-fpm.log -Generic logs for PHP apps. - -##### yunohost.log -This is the log created at the YunoHost install. If you have issue installing YunoHost, check this file. - -##### YunoHost operations logs -This is the logs created when you install, remove, backup, etc... an apps, they can be found using the Webadmin in Tools > Logs or using the command line: `yunohost log list` and `yunohost log display`. - -This list is not exhaustive. Furthermore, some app may put their logs in `/var/log` too. Slapd logs are unfortunately in `/var/log/syslog`. - -## RAM usage -Issues can be caused by a lack of RAM. To check your memory usage, do the following command: -```bash -free -m -``` - - -5-10% of free memory is fine but it's good to have margin (especially for upgrade). Since most of the time you can't upgrade your physical RAM, alternative it to use a swap file. Keep in mind that swap it's a memory 100.000 times slower, so you may to use it only if you got no other choice. - -##### Create a swap file: -If `free -m` indicate that you have 0 total for swap line, you may want to add a swap file. -```bash -sudo install -o root -g root -m 0600 /dev/null /swapfile -dd if=/dev/zero of=/swapfile bs=1k count=512k -mkswap /swapfile -swapon /swapfile -echo "/swapfile swap swap auto 0 0" | sudo tee -a /etc/fstab -sudo sysctl -w vm.swappiness=10 -echo vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf -``` - -Change 512 with the quantity of swap memory you want, 512Mb should be enough for YunoHost. After that, check with `free -m` that you swap is activated. -[Source with more explanation](https://meta.discourse.org/t/create-a-swapfile-for-your-linux-server/13880). - -## Disk space -One other common issue on a server is lack of disk space. You can check your filesystem are not full with the command: -```bash -df -h -``` -This will show you disk usage, if one file-system is near to be full you could encounter issues. You should take appropriate actions to free space or extend your file-system. - - - -## Nginx -Nginx play a big part in YunoHost since it serve all the web applications. YunoHost have a specific way to handle its configuration since there are multiple domain and multiple applications. - -### Configuration -##### General configuration structure -```bash -# Main nginx configuration, you don't want to touch this file -/etc/nginx/nginx.conf -# Directory where all YunoHost, domain and app config are located -/etc/nginx/conf.d/ -# Configuration of web administration -/etc/nginx/conf.d/yunohost_admin.conf -# Per domain configuration (one per domain) -/etc/nginx/conf.d/example.com.conf -``` - -##### Application configuration -For each application on a given domain there is a Nginx conf file located in: -```bash -/etc/nginx/conf.d/example.com.d/appname.conf -``` -Application configuration file usually follow this type of pattern -```bash -location YNH_WWW_PATH { # path to access the app in browser - alias YNH_WWW_ALIAS ; # Path to source, usually /var/www/app_name - -# Specific configuration for the application according to its programming language and deployment option -... -... -# Include SSOWAT user panel in bottom right -include conf.d/yunohost_panel.conf.inc; -} -``` - -### Logs -Nginx logs files are located in the directory: -```bash -/var/log/nginx/ -``` -#### Generic logs -##### access.log -Generic access logs, you will find here all the accesses to the YunoHost administration and sometimes intrusion tentative. - -##### error.log -Should be empty with a correct Nginx config. If Nginx doesn't start, error are probably located in this log. - -#### For each domain name -##### example.com-access.log -All accesses to the domain, including all apps. - -##### example.com-error.log -All error regarding app installed on the domain. - -Sometime application may have their logs located here too. - -## SSOwat -[SSowat](https://github.com/Kloadut/SSOwat) is the software that connect the web server nginx to the LDAP server. His purpose is to authentificate users to the YunoHost portal to switch easily between apps. - -### Configuration -You can view (don't edit it, it is oftently overwritten) your current SSOwat config in the file: -```bash -/etc/ssowat/conf.json -``` -Which is generated with the command: -```bash -yunohost app ssowatconf -``` -Protip: if you want to add a personalized rule for SSOwat, do it in this file: -```bash -/etc/ssowat/conf.json.persistent -``` -### Logs -There is no specific logs for SSOwat. There are are located in Nginx logs files. If you see some line with `lua` in it, it's probably SSOwat. - -## YunoHost -### Configuration -YunoHost configuration is located in: -```bash -/etc/yunohost/ -``` -If you want to keep a custom service configuration use this file: -```bash -/etc/yunohost/yunohost.conf -``` -For all the service you pass `yes`, YunoHost will not upgrade the config of the specified service. Do this only if you know what you're doing. - -All apps configurations are located in: -```bash -/etc/yunohost/apps/app_name/ -``` -In each app packages you will find: - -* **manifest.json**: manifest of the app -* **scripts/**: directory containing five Shell scripts to manage apps - * install - * upgrade - * remove - * backup - * restore -* **config/**: config directory -* **settings.yml**: config of the app, also accessible with: -```bash -yunohost app setting appname settingname -``` - -### Logs -There is no logfile for application install so when you install an app, keep the log. There is some log about the command line usage in: -```bash -/var/log/yunohost/ -``` - -## Applications -This part is more for packager or to understand the link between Nginx and webapps. First, you should know [how to package a new app](/packaging_apps). - -When troubleshooting an application issue can occur at several levels. There is a wide variety of applications and their deployment to YunoHost will depending on the programming language of the app. We will deal here with the most commons cases. -Applications configurations are not treated because it completely differs according to the application. - -##### Oversimplified schema -Web browser −> Nginx <− (web server) <− runtime (PHP, Python, Node.js,...) <− app - -App is interpretated by the runtime, runtime provide or not a webserver, if not a webserver can be added, webserver or runtime communicate with Nginx, Nginx serve webpage to the web browser. - -The purpose of this configuration is to have multiple application on one server with only the https port (443) open to the whole Internet. - -### PHP apps -##### Deployment option -PHP works natively with Nginx. - -##### Communication with Nginx -The PHP interpreter communicate with Nginx through [PHP-FPM](http://php-fpm.org/) which is a [FastCGI](http://en.wikipedia.org/wiki/FastCGI) implementation. - -##### Logs -```bash -/var/log/php5-fpm.log -``` -**YunoHost package example**: [Owncloud](https://github.com/Kloadut/owncloud_ynh). - -### Python apps -##### Deployment option -A Python webapp should run with it's own Python interpreter with and it's own dependencies, for this, the tool `virtualenv` is used. -Usually, a light web server will be used to serve the app behind Nginx. [Uwsgi](https://uwsgi-docs.readthedocs.org/en/latest/) is a good example. - -##### Communication with Nginx -Nginx can talk to Python server via three ways: -- [proxy_pass](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) -- Websocket -- Native uwsgi: uwsgi_pass: [for instance](https://github.com/abeudin/searx_ynh/blob/master/conf/nginx.conf#L9-L10) - -##### Logs -Specific to the app and/or the webserver used, for instance uwsgi: -```bash -/var/log/uwsgi/ -``` -##### Ressources -[Great resource in french on Python virtualenv](http://sametmax.com/les-environnement-virtuels-python-virtualenv-et-virtualenvwrapper/) - -**YunoHost package example**: [Searx](https://github.com/abeudin/searx_ynh) - -### Node.js apps -##### Deployment option -A Node.js app have it's own web server integrated in node runtime, usually Node will expose the app to a TCP port. - -##### Communication with Nginx -The http endpoint will be passed locally to Nginx via proxy_pass. - -##### Logs -This will be specific to the app. - -**YunoHost app example:** [Etherpad-Lite](https://github.com/abeudin/etherpadlite_ynh). - -**Note**: Node process can use **lot** of memory compared to other app processes, make sure you have enough. - -### Other (Go, Java...) -Webapp can take multiple form an can be deployed in many way. Go app have usually an integrated webserver, Java can be deployed with Tomcat or equivalent… There is no way to be exhaustive here, but most of the time your deployment option will expose an http endpoint that you can pass to Nginx via proxy_pass. - -##### Note on Apache -Never install Apache or a package withe Apache as dependency, this will probably break your YunoHost intance. - -##### Note on https -Sometimes the webserver integrated with the app is capable to serve https on its own, it's right to use this when you have one application on one server and you don't want to install Nginx for intance. But in YunoHost case, Nginx who serve https and it simplify configuration. So when passing the local URL to Nginx via proxy_pass, use http, nginx will https the thing to the open world later. diff --git a/troubleshooting_guide_fr.md b/troubleshooting_guide_fr.md deleted file mode 100644 index 15969124..00000000 --- a/troubleshooting_guide_fr.md +++ /dev/null @@ -1,366 +0,0 @@ -# Guide de dépannage de YunoHost - -Vous pouvez considérer ce guide comme une sorte de guide de dépannage permettant de voir ce qu’il faut regarder quand vous rencontrez un problème avec votre serveur YunoHost. Ce n’est pas un guide pour remettre en état votre instance YunoHost mais plutôt une liste de choses à vérifier pour aider à diagnostiquer les problèmes rencontrés. -Ce guide peut trouver son intérêt lors du débuggage d’une nouvelle application ou pour comprendre l’architecture de Yunohost. - -## Notes générales -### Ne cassez pas YunoHost -La meilleure manière de ne pas avoir de pannes est de ne pas bricoler sur votre serveur. Cela signifie que dès que vous souhaitez essayer quelque chose de nouveau (application non officielle, nouvelle configuration personnalisée, création d’une nouvelle application), essayez d'abord cela sur un serveur de test et non de production. Pour faire cela, vous pouvez par exemple utiliser une [virtualbox](/install_on_virtualbox) ou un [droplet DigitalOcean](/install_on_vps) pour 1 centime/heure. - -Vous pouvez aussi lire ceci si vous avez encore envie de bricoler sur votre instance YunoHost en production : https://wiki.debian.org/DontBreakDebian - -### N'installez pas d'applications de mauvaise qualité - -Bien que ce soit tentant d’installer toutes les [applications](/apps), faites attention à leur niveau de qualité car une mauvaise application peut casser votre serveur. Si la qualité d'une application laisse à désirez mais que vous souhaitez tout de même absolument l'installer, essayez de faire ça sur un serveur de test, ou vérifiez au minimum si des problèmes ont été remontés sur le dépôt Github associé ou bien sur le [forum](http://forum.yunohost.org/). - -### Vérifier la documentation officielle -Les réponses à vos questions existent peut être déjà dans [la documentation](/docs). - -### Vérifier l’aide dans les commandes en ligne -Vous pouvez apprendre à utiliser les [commandes YunoHost](/commandline) - -## Mise à jour -Les problèmes ont souvent lieu après une mise à jour. Après une mise à jour, vous pouvez avoir envie de [mettre à jour votre application](/app_update). - - -**Vérifier si un processus utilise une ancienne librairie** -vous avez sûrement l’habitude d’utiliser : -```bash -$ apt update && apt dist-upgrade -``` -La plupart du temps, cela suffit. Mais dans certaines situations, il est possible que certains processus utilisent toujours d’anciennes bibliothèques non mises à jour. -Cela peut entraîner des bugs et, dans certains rares cas, des problèmes de sécurité (ex : lors d’une mise à jour de OpenSSL à cause d’une faille de sécurité, Nginx va continuer à utiliser la version dont il dispose en mémoire). L’utilitaire Checkrestart va vous aider à identifier ces processus et les redémarrer. - -```bash -$ apt install debian-goodies -checkrestart -# Found 0 processes using old versions of upgraded files -``` -Si des processus fonctionnent avec des vieilles versions de bibliothèques, checkrestart va vous le dire et vous proposer une manière de les redémarrer. Il est possible que checkrestart ne trouve pas de manière de les redémarrer. Attention, il faut opérer l’opération manuellement. - - - -La solution la plus simple peut être de redémarrer si vous pouvez - -Vous pouvez aussi utiliser [ce script](https://github.com/octopuce/octopuce-goodies/blob/master/checkrestart/checkrestart.octopuce) pour redémarrer automatiquement ces services si besoin. Plus d’informations [ici](https://www.octopuce.fr/checkrestart-outil-pratique-de-debian-goodies-et-version-octopuce/). - -**Forcer une mise à jour d’une application non officielle** - -/!\ Pensez toujours à vérifier s’il existe un script de mise à jour et lisez-le si vous pouvez/!\ - - -```bash -$ yunohost app upgrade -Warning: You must provide an URL to upgrade your custom app app_name -Error: No app to upgrade - -$ yunohost app upgrade -u https://github.com/user/someapp_ynh app_name -``` - -## Les services -YunoHost utilise toute une série de logiciels pour fonctionner. La plupart de ces logiciels sont déclarés comme des services dans Debian [plus d’info](/whatsyunohost). - -### Vérifier le statut des services -Quand quelque chose ne fonctionne pas, une des premières choses à faire est de vérifier que tous les services utilisés par YunoHost sont lancés. -YunoHost inclus un outil qui permet de visualiser tous les services utilisés par YunoHost : -```bash -yunohost service status -``` -Exemple de résultat : - - - -Tous les services doivent être activés (enabled) et en fonctionnement (running) sauf Glances (optionnel). Si certains ne le sont pas, essayez de les redémarrer. -Voici une petite description de leurs fonctions respectives : - -- **Amavis** : anti-spam/virus/malwares, utilisé lors de l’échange de mails. -- **Avahi-daemon** : système qui facilite la découverte d’ordinateurs sur le réseau local en leur attribuant des noms. -- **DNSmasq** : serveur DNS, vous n’êtes pas obligé de l’utiliser (Non installé par défaut) -- **Dovecot** : serveur IMAP, utilisé pour la réception de mails. -- **Glances** : optionnel, utilisé pour l’administration web pour afficher les statuts du serveur -- **Metronome** : serveur XMPP utilisé par jappix comme client. -- **MySQL** : base de données utilisée par certaines applications -- **Nginx** : serveur web, utilisé par toutes les applications -- **php5-fpm** : serveur PHP, utilisé par toutes applications utilisant PHP -- **Postfix** : serveur SMTP, utilisé pour l’envoi de mails. -- **Postgrey** : serveur de listes grises, si vous utilisez YunoHost pour les mails, vous devriez regarder un peu plus sur cette question. -[En apprendre plus sur les listes grises](http://en.wikipedia.org/wiki/Greylisting) -- **Slapd** : serveur LDAP, utilisé pour l’authentification (SSO and apps) -- [**SSH**](/ssh) : Secure Shell, utilisé pour l’accès distant au serveur. -- [**SSOwat**](https://github.com/Kloadut/SSOwat/) : gestionnaire simple d’authentification. -- **YunoHost-API** : administration web de YunoHost - -Les autres services installés par des applications vont aussi apparaître. Par exemple `seafile-serve` utilisé par l’application Seafile et `uwsgi` qui est utilisé par des applications python comme Searx. -##### démarrer ou arrêter un service identifié avec YunoHost : -```bash -yunohost service start -yunohost service stop -``` -Vous pouvez aussi utiliser la commande Debian : -```bash -systemctl start/stop/restart/reload -``` -Après une tentative de lancement, vérifiez toujours que le service est lancé. - -### Logs -Si un service ne démarre pas, vous devez vérifier les logs pour voir ce qui ne pose problème. Il n’y a pas de règles définies où les services doivent stocker leurs logs. Cependant, ceux-ci se trouvent pour la plupart dans : -```bash -/var/log/ -``` -Voici quelques fichiers de log utiles pour YunoHost : -##### auth.log -Il contient les connexions ou tentatives de connexion à votre serveur. Il inclut aussi toutes les connexion web, ssh et cron job (tâches répétitives). Il stoque enfin toutes les tentatives (on l’espère) de connexion par des potentiels intrus. - -##### fail2ban.log -Quand quelqu’un tente de se connecter à votre serveur et rate plusieurs fois, Fail2ban bannit l’adresse IP afin d’éviter les attaques en bruteforce et/ou en (D)DOS. Vous pouvez donc trouver ici les IP qui auront été bannies. - -##### mail.err, mail.info, mail.log, mail.warn -Ce sont les logs de Postfix pour le serveur de mail. Vous pouvez les consulter si vous rencontrez des problèmes avec les mails. - -##### metronome/metronome.err, metronome/metronome.log -Logs du serveur de chat XMPP - -##### mysql.err, mysql.log, mysql/error.log -Logs de la base de données MySQL. Ils doivent être vides sauf si vous avez des problèmes avec MySQL. - -##### php7.0-fpm.log -Lieu générique d’emplacement des logs pour les applications PHP. - -##### yunohost.log -C’est le fichier de log créé à l’installation de YunoHost. Si vous rencontrez des problèmes à l’installation de YunoHost, vérifier ce fichier. - -Cette liste n’est pas exhaustive. De plus, certaines applications peuvent aussi mettre leurs fichiers de log dans `/var/log`. -Les logs de Slapd sont malheureusement stockés dans`/var/log/syslog`. - -## Utilisation de la RAM -Des problèmes peuvent être causés par un manque de RAM. Pour vérifier votre utilisation de la RAM, entrez la commande suivante : -```bash -free -m -``` - - -5 à 10 % de mémoire libre est acceptable, mais il est bien de disposer d’une marge (en particulier pour les mises à jour). Comme la plupart du temps, vous ne pouvez pas augmenter votre quantité de RAM, vous avez la possibilité d’utiliser une partition de SWAP (mémoire du disque dur attribuée à la RAM). -Gardez à l’esprit que le SWAP est une mémoire 100 000 fois plus lente, vous devriez donc l’utiliser uniquement si vous n’avez pas d’autre choix. - -##### créer un fichier de swap : -Si `free -m` indique que vous n’avez aucune ligne de SWAP, vous pouvez avoir envie d’ajouter un fichier de SWAP. -```bash -sudo install -o root -g root -m 0600 /dev/null /swapfile -dd if=/dev/zero of=/swapfile bs=1k count=512k -mkswap /swapfile -swapon /swapfile -echo "/swapfile swap swap auto 0 0" | sudo tee -a /etc/fstab -sudo sysctl -w vm.swappiness=10 -echo vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf -``` - -Changez 512 avec la quantité de mémoire SWAP que vous voulez. -512 Mio devrait être suffisant pour YunoHost. Après quoi, vérifiez que votre swap est activé avec `free -m`. -[Source avec plus d’explication](https://meta.discourse.org/t/create-a-swapfile-for-your-linux-server/13880). - -## Espace disque -Un des autres problèmes communs des serveurs est le manque d’espace disque. -Vous pouvez vérifier que votre disque n’est pas plein avec la commande : -```bash -df -h -``` -Cela va vous montrer l’utilisation du disque. Si une partition système est presque pleine, vous pouvez rencontrer des problèmes. Vous devez alors réaliser les opérations appropriées pour gagner de l’espace libre sur le disque ou étendre la capacité de celui-ci. - - - - - -## Nginx -Nginx joue un grand rôle dans YunoHost puisqu’il fournit toutes les applications web. -YunoHost a une manière particulière de gérer la configuration puisqu’il existe plusieurs domaines et plusieurs applications. - -### Configuration -##### Configuration générale de la structure -```bash -# Configuration principale de Nginx, vous ne devriez pas toucher ce fichier -/etc/nginx/nginx.conf -# Dossier où les configurations de toutes les applications et domaines sont situées - /etc/nginx/conf.d/ -# Configuration de l’administration web -/etc/nginx/conf.d/yunohost_admin.conf -# Configuration par domaine (une par domaine) - /etc/nginx/conf.d/example.com.conf -``` - -##### Configuration des applications -Pour chaque application ou domaine donné, il y a un fichier de configuration Nginx situé dans : -```bash -/etc/nginx/conf.d/example.com.d/nom_de_application.conf -``` -Les fichiers de configuration sont généralement utilisés pour ce genre de modèle - -```bash -location YNH_WWW_PATH { # Chemin pour atteindre votre application dans le navigateur -alias YNH_WWW_ALIAS ; # chemin pour accéder aux sources des fichiers aux fichiers (d’habitude /var/www/app_name) - -# Configuration particulière pour une application selon son langage de programmation et ses options de déploiement. - -# Inclure le logo SSOwat en bas à droite de la fenêtre -include conf.d/yunohost_panel.conf.inc; -} -``` - -### Les logs -Les fichiers de log de Nginx sont situés dans le dossier : - -```bash -/var/log/nginx/ -``` -#### Logs génériques -##### access.log -Le fichier générique d’accès. Vous trouverez ici toutes les tentatives d’accès à l’administration de YunoHost et certaines tentatives d’intrusion. - -##### error.log -Ce fichier devrait être vide avec une configuration correcte de Nginx. Si Nginx ne démarre pas, des informations sur les erreurs devraient se trouver dans ce fichier. - - -#### Pour chaque nom de domaine -##### example.com-access.log -Tous les accès à ce domaine (en prenant en comptes toutes les applications). - -##### example.com-error.log -Toutes les erreurs liées aux applications installées sur ce domaine, il se peut que certaines applications aient tous leurs logs soit dans ce fichier. - - -## SSOwat -[SSowat](https://github.com/Kloadut/SSOwat) -est le logiciel qui connecte le serveur web nginx au serveur LDAP. Son but est d’authentifier les utilisateurs au portail YunoHost pour pouvoir simplement se déplaçer entre les applications. - -### Configuration -Vous pouvez regarder le fichier de configuration SSOwat dans le fichier : - -```bash -/etc/ssowat/conf.json -``` -Celui-ci est généré avec la commande -```bash -sudo yunohost app ssowatconf -``` -Astuce : si vous souhaitez mettre en place des règles personnalisées dans le SSOwat, vous pouvez le faire dans ce fichier : -```bash -/etc/ssowat/conf.json.persistent -``` -### Logs -Il n’y a pas de fichier de log spécifiques pour SSOwat. Ils sont situés dans les fichiers de log de Nginx. Si vous voyez des lignes avec `lua` à l’intérieur, il s’agit probablement de logs de SSOwat. - -## YunoHost -### Configuration -La configuration de Yunohost est située ici -```bash -/etc/yunohost/ -``` -Si vous souhaitez utiliser et conserver un fichier de configuration personnalisé, utiliser ce fichier : -```bash -/etc/yunohost/yunohost.conf -``` -Pour tous les services avec la mention `yes`, YunoHost ne réalisera pas de mise à jour des services spécifiés. -Ne faites ça que si vous savez ce que vous faites. - -Toutes les configurations d’applications sont situées dans : -```bash -/etc/yunohost/apps/app_name/ -``` -Dans chaque paquet (d’application), vous trouverez : - - -* **manifest.json** : manifeste de l’application -* **scripts/** : dossier contenant cinq scripts Shell pour gérer l’application. - * install - * upgrade - * remove - * backup - * restore -* **config/** : dossier de configuration -* **settings.yml** : La configuration de l’application, aussi accessible via : -```bash -sudo yunohost app setting appname settingname -``` - -### Logs -Il n’y a pas de fichier de log créé lorsque vous installez une application. Essayez de conserver les logs. Vous pouvez trouver cependant certains logs peuvent se trouver dans : -```bash -/var/log/yunohost/ -``` - -## Applications -Cette partie concerne plus les créateurs d’applications YunoHost mais permet néanmoins de comprendre le lien entre Nginx et les applications web. - -Premièrement, vous devez savoir [comment créer un paquet pour une nouvelle application](/packaging_apps). - -Quand vous bricolez une application, des erreurs peuvent avoir lieu selon certains niveaux d’importance. Il y a une grande variété d’applications et le déploiement de celles-ci va dépendre du langage de programmation de l’application. -Nous allons voir ici les « cas classiques ». -La configuration des applications n’est pas abordée ici car leurs configurations respectives peuvent énormément varier. - -##### Schéma simplifié -Navigateur web −> Nginx <− (serveur web) <− interpréteur (PHP, Python, Node.js…) <− app - -L’application est exécutée par l’interpréteur, celui-ci peut potentiellement fournir un serveur web. Le runtime ou le serveur web va communiquer avec Nginx et ce dernier servira des pages au navigateur web. - -Le but de cette configuration est d’avoir plusieurs applications sur un seul serveur avec seulement le port https ouvert à l’internet entier. - -### Applications PHP -##### Options de déploiement -PHP fonctionne nativement avec Nginx - -##### La communication avec Nginx -L’interpréteur PHP communique avec Nginx par [PHP-FPM](http://php-fpm.org/) -qui est une implémentation de [FastCGI](http://en.wikipedia.org/wiki/FastCGI) implémentation. - -##### Les logs -```bash -/var/log/php5-fpm.log -``` -**Exemple de paquet YunoHost** : [Owncloud](https://github.com/Kloadut/owncloud_ynh). - -### Applications Python -##### Options de déploiement -Une application python devrait fonctionner avec son propre interpréteur Python et ses propres dépendances. Pour cela, on peut utiliser l’outil `virtualenv`. -D’habitude, un serveur web léger sera utilisé pour fournir l’application derrière Nignx [Uwsgi](https://uwsgi-docs.readthedocs.org/en/latest/) est un bon exemple. - - -##### La communication avec Nginx -Nginx communique de trois manières avec Python : - -- [proxy_pass](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) -- Websocket -- Native uwsgi : uwsgi_pass : [par exemple](https://github.com/abeudin/searx_ynh/blob/master/conf/nginx.conf#L9-L10) - -##### Logs -Logs spécifiques à l’application et/ou au serveur web, par exemple uwsgi : -```bash -/var/log/uwsgi/ -``` -##### Ressources -[Bonnes ressources en français sur Python et virtualenv](http://sametmax.com/les-environnement-virtuels-python-virtualenv-et-virtualenvwrapper/) - -**Exemple de paquet YunoHost en Python** : [Searx](https://github.com/abeudin/searx_ynh) - -### Applications Node.js -##### Options de déploiement -Une application Node.js a son propre serveur web intégré dans l’interpréteur Node. D’habitude, Node va exposer l’application sur un port TCP. - -##### Communication avec Nginx -Le point d’accès http va être réalisé en local vers Nginx via proxy_pass. - -##### Les Logs -Cela va être spécifique aux applications. - -**Exemple de paquet YunoHost en Node.js :** [Etherpad-Lite](https://github.com/abeudin/etherpadlite_ynh). - -**Note** : les processus Node peuvent utiliser **beaucoup** de mémoire comparée aux processus des autres applications. Assurez-vous donc d’en avoir assez. - -### Autres (Go, Java…) -Les webapp peuvent être déployées de nombreuses manières. -Les applications Go ont généralement un serveur web intégré, Java peut être déployé avec Tomcat ou une autre solution équivalente. Il n’est pas possible d’être exhaustif ici mais la plupart du temps, les déploiements vont exposer une adresse en http que vous pourrez passer dans Nginx via proxy_pass. - -##### Note sur Apache -Ne jamais installer le serveur web Apache ou un paquet avec Apache comme dépendance, cela va sûrement casser l’instance YunoHost. - -##### Note sur https -Parfois, le serveur web intégré avec l’application est capable de servir du https lui-même. -C’est une bonne chose de l’utiliser quand vous disposez d’une application sans Nginx devant. Dans le cadre de YunoHost, le fait que Nginx serve du https simplifie la configuration. Donc, quand vous passez par proxy_pass, utilisez http et Nginx le mettra a disposition en https pour le reste de l’internet.