On a regular computer

Pré-requis

• A x86-compatible hardware dedicated to YunoHost with at least 512MB of RAM and 16GB of disk
  • this may be an old laptop, desktop computer, or a proper server machine
• A 1GB+ USB key
• A reasonable ISP, preferably with good and unlimited upstream bandwidth
• An ethernet cable (RJ-45) to connect your server to your router.
• A computer to read this guide, flash the image and access your server.

Download the YunoHost image

attention

If your machine is 32 bits, be sure to download the 32-bit image.

info

(FIXME: this bit is currently broken...)

Optionally, you can download the project's public key to check the authenticity of the images.

Flash the YunoHost image

Flash the image on the USB key or CD/DVD.

Avec Etcher (recommandé)

Download Etcher for your operating system and install it.

Plug your USB key, select your image and click "Flash"

Avec USBimager

Téléchargez USBimager pour votre système d'exploitation et installez-le.

Plug your USB key, select your image and click "Write"

Avec dd

If you are on GNU/Linux / macOS and know your way around command line, you may also flash your USB stick or SD card with dd. You can identify which device corresponds to your USB stick or SD card with fdisk -l or lsblk. A typical SD card name is something like /dev/mmcblk0. BE CAREFUL and make sure you got the right name.

Then run:

# Replace /dev/mmcblk0 if the name of your device is different...
dd if=/path/to/armbian.img of=/dev/mmcblk0 status=progress ; sync

Using Ventoy

Ventoy will be useful if you can't sucessfully boot the YunoHost image using the other methods.

Ventoy is a nice tool that makes it really easy to put multiple linux images on a USB stick. When the computer refuses to boot from an image on a USB stick, Ventoy will usually be able to boot it anyway!

1. Install Ventoy on the USB stick. Refer to the install instructions.
   • This will create 2 partitions on the stick.
2. Using your favorite file explorer app, copy the YunoHost image file on the big Ventoy partition (not "VTOYEFI")
   • Don't use Balena Etcher, USBImager or dd for this!

Later, when you'll boot the computer using this USB stick, Ventoy will appear and will list the images on the USB stick. Select the YunoHost image, then select GRUB2 launch option (or use whichever works for your computer 😉)

Boot the machine on your USB stick

• Connect your computer to your home router via Ethernet
• Boot up your server with the USB stick or a CD-ROM inserted, and select it as bootable device.
  • Depending on your hardware, you will need to press one of the following keys: <F9>, <F10>, <F11>, <F12>, <DEL>, <ESC> or <Alt>.
  • N.B. : if the server was previously installed with a recent version of Windows (8+), you first need to tell Windows, to "actually reboot". This can be done somewhere in "Advanced startup options".

astuce

If you can't boot the YunoHost image, try using Ventoy (select "Ventoy" in the section "Flash the YunoHost image" above).

Launch the graphical install

You should see a screen like this:

Preview of the ISO menu

Classic installation on a whole disk

danger

Once you have validated the keyboard layout, the installation will be launched and will completely erase the data on your hard disk!

1. Select Graphical install
2. Select your language, your location, your keyboard layout, and eventually your timezone.
3. The installer will then download and install all required packages.

Installation in expert mode

The YunoHost project simplified the classic installation as much as possible in order to avoid as many people as possible being lost with questions that are too technical or related to specific cases.

With the expert mode installation, you have more possibilities, especially concerning the exact partitioning of your storage media. You can also decide to use the classic mode and add your disks afterwards.

Summary of the steps in expert mode

1. Select Expert graphical install.
2. Select your language, location, keyboard layout and possibly your timezone.
3. Partition your disks. This is where you can set up a RAID or encrypt all or part of the server.
4. Specify a possible HTTP proxy to use for the installation of the packages
5. Specify on which volumes grub should be installed

Regarding partitioning

In general, we recommend against partitioning /var, /opt, /usr, /bin, /etc, /lib, /tmp and /root on separate partitions. This will prevent you from having to worry about full partitions that could crash your machine, cause app installations to fail, or even corrupt your databases.

For performance reasons, it is recommended to mount your fastest storage (SSD) on the root /.

If you have one or more hard drives to store data, you can choose to mount it on one of these folders depending on your usage.

Path	Contents
/home	User folders accessible via SFTP
/home/yunohost.backup/archives	YunoHost backups to be placed ideally elsewhere than on the disks that manage the data
/home/yunohost.app	Heavy data from YunoHost applications (nextcloud, matrix...)
/home/yunohost.multimedia	Heavy data shared between several applications
/var/mail	User mail

If you want flexibility and don't want to (re)size partitions, you can also choose to mount on /mnt/hdd and follow this tutorial to mount all these folders with mount --bind.

About encryption

Be aware that if you encrypt all or part of your disks, you will have to type the passphrase every time you restart your server, which can be a problem if you are not on site. There are however solutions (quite difficult to implement) that allow you to type the passphrase via SSH or via a web page (search for "dropbear encrypted disk").

About RAID

Keep in mind that:

• the disks in your RAIDs must be of different brands, wear and tear or batches (especially if they are SSDs)
• a RAID 1 (even without a spare) is more reliable than a RAID 5 from a probability point of view
• hardware raids are dependent on the raid card, if the card fails you will need a replacement to read and rebuild the array

info

If the YunoHost installer fails and you can't solve the issue, know that it's also possible to install Debian and then install YunoHost on top. See the specific instructions.

Lancer la configuration initiale

info

Si vous êtes en train de restaurer une sauvegarde YunoHost, vous devez sauter cette étape et vous référer à la section Restaurer durant la post-installation à la place de cette étape de configuration initiale.

info

Cette documentation suppose que vous êtes sur le même réseau local que votre YunoHost.

Pour un VPS, utilisez l'adresse IP publique au lieu du domaine ou adresse locale.

Depuis la webadmin

Depuis un ordinateur, ouvrez un navigateur et tenter d'accéder à la webadmin:

• si vous installez sur un VPS, vous avez probablement utilisé la méthode d'installation basée sur curl | bash, et le script aurait du vous pointer vers l'adresse, typiquement https://xx.xx.xx.xx (avec l'IPv4 publique du serveur)
• si vous installez à la maison, et en supposant que vous êtes sur le même réseau local que le serveur
  • vous pouvez tenter d'ouvrir https://yunohost.local (ceci peut ou peut ne pas fonctionner en fonction de si votre machine et réseau supporte le protocole Bonjour)
  • si vous connaissez déjà l'IP locale du serveur, allez sur https://xx.xx.xx.xx (avec l'IP locale, typiquement qui commence par 192.168.)
  • autrement, il vous faut trouver l'IP locale du serveur pour continuer.

attention

Lors de la première visite, vous rencontrerez très probablement un avertissement de sécurité lié au certificat utilisé. Pour le moment, votre serveur utilise un certificat auto-signé. Vous pourrez plus tard ajouter un certificat automatiquement reconnu par les navigateurs comme décrit dans la page sur les certificats. En attendant, ajoutez une exception de sécurité pour accepter le certificat actuel. (Toutefois, s'il vous plaît, ne prenez pas l'habitude d'accepter ce genre d'alerte de sécurité !)

Vous devriez arriver sur cette page:

Capture d'écran de la page de configuration initiale

Depuis la ligne de commande

Vous pouvez aussi lancer la post-installation avec la commande yunohost tools postinstall directement sur le serveur ou via SSH.

Capture d'écran de la configuration initiale en ligne de commande

Domaine principal

Configuration spécifique WSL

Vous devrez choisir un faux nom de domaine, car il ne sera pas accessible de l'extérieur. Par exemple, ynh.wsl. L'étape compliqué est d'exposer ce nom de domaine à votre hôte.

Éditez le fichier C:\Windows\System32\drivers\etc\hosts. Vous devriez avoir une ligne commençant par ::1, créez la si elle n'existe pas, et rajoutez votre domaine à la fin:

::1    ynh.wsl localhost

Si vous voulez des sous-domaines, n'oubliez pas de les y rajouter auss dans le fichier hosts:

::1    ynh.wsl subdomain.ynh.wsl localhost

C’est le nom de domaine qui permettra l’accès à votre serveur ainsi qu’au portail d’authentification des utilisateurs. Vous pourrez ensuite ajouter d'autres domaines, et changer celui qui sera le domaine principal si besoin.

• Si l'auto-hébergement est tout nouveau pour vous, et que vous n'avez pas encore de nom de domaine, nous recommandons d'utiliser un domaine en .nohost.me / .noho.st / .ynh.fr (exemple : homersimpson.nohost.me). S'il n'est pas déjà utilisé, le domaine sera automatiquement rattaché à votre serveur, et vous n’aurez pas d’étape de configuration supplémentaire. Toutefois, notez que l'utilisation d'un de ces noms de domaines implique que vous n'aurez pas le contrôle complet sur votre configuration DNS.
• Si vous disposez déjà d'un nom de domaine, alors vous voulez probablement l'utiliser ici. Il vous faudra plus tard configurer les enregistrements DNS comme expliqué ici.

astuce

Oui, vous devez configurer un nom de domaine. Si vous n'avez pas de nom de domaine et que vous n'en voulez pas en .nohost.me, .noho.st ou .ynh.fr, vous pouvez utilisez un « faux » domaine comme par exemple yolo.test et modifier votre fichier /etc/hosts sur votre ordinateur local pour que ce domaine pointe vers l'IP de votre serveur, comme expliqué ici.

Premier compte utilisateur⋅ice

Le premier compte utilisateur est créé à cette étape. Il vous faudra choisir un nom d'utilisateur et un mot de passe raisonablement complexe. (Nous ne pouvons que souligner l'importance du choix d'un mot de passe robuste !) Ce compte utilisateur sera ajouté au groupe Admins, et pourra se connecter au portail utilisateur, à la webadmin, et se connecter via SSH ou SFTP. Les admins recevront aussi les mails envoyés à root@votredomaine.tld et admin@votredomaine.tld : ces emails peuvent être utilisés pour envoyer des informations ou des alertes techniques. Vous pourrez plus tard ajouter d'autres comptes supplémentaires, qu'il est aussi possible d'ajouter au groupe Admins.

Ce compte remplace l'ancien compte admin, qui est peut être toujours mentionné dans certaines pages de documentation. Dans ce cas, remplacez simplement admin par votre identifiant.

Lancer le diagnostic

Une fois la postinstall terminée, vous devriez pouvoir vous connecter à la webadmin en utilisant les identiants du premier compte que vous venez de créer.

Le système de diagnostic est conçu comme un moyen facile de valider que tous les aspects critiques de votre serveur sont proprement configurés et pour vous guider dans la résolution des problèmes soulevés. Le diagnostic se lance deux fois par jour et envoie une alerte par email si un dysfonctionnement est détecté.

astuce

Ne partez pas en courant ! La première fois que vous lancerez le diagnostic, il est assez normal d'avoir plusieurs alertes rouges ou jaunes car vous devez généralement configurer les enregistrements DNS (si vous n'utilisez pas un domaine .nohost.me, .noho.st ou .ynh.fr), ajouter un fichier de swap ainsi que configurer la redirection des ports sur votre box.

astuce

Si une alerte n'est pas pertinente (par exemple parce que vous ne pensez pas utiliser une fonctionnalité spécifique), il est tout à fait convenable d'indiquer le dysfonctionnement comme « À ignorer » en allant dans l'administration web > Diagnostic, et en cliquant sur le bouton « Ignorer » pour ce dysfonctionnement spécifique.

attention

Notamment, les installations WSL ou sur machines virtuelles ne seront généralement pas accessibles de l'extérieur sans une configuration réseau avancée sur Virtualbox et son hôte.

(Recommandé) Depuis l'interface web

Pour lancer le diagnostic, allez dans la webadmin, dans la partie Diagnostic. Vous devriez obtenir un écran comme celui-ci :

Capture d'écran du panneau de diagnostic

Depuis la ligne de commande

yunohost diagnosis run
yunohost diagnosis show --issues --human-readable

Obtenir un certificat Let's Encrypt

Une fois que vous avez configuré, si nécessaire, les enregistrements DNS et la redirection de ports, vous devriez être en mesure d'installer un certificat Let's Encrypt. Ceci permettra de supprimer l'effrayante alerte de sécurité vue plus tôt.

Pour plus d'instructions détaillées, ou pour en savoir plus à propos des certificats SSL/TLS, voir la page correspondante ici.

Depuis la webadmin

Allez dans Domaines > le domaine concerné > Certificat

Capture d'écran du panneau pour installer un certificat Let's Encrypt

Depuis la ligne de commande

yunohost domain cert install

🎉 Félicitations !

Vous avez maintenant un serveur plutôt bien configuré. Si vous découvrez YunoHost, nous vous recommandons de jeter un œil à la visite guidée. Vous devriez aussi être en mesure d'installer vos applications favorites. N'oubliez pas de prévoir des sauvegardes !