Install YunoHost

Select the hardware on which you want install YunoHost :

Pre-requisites

  • A x86-compatible hardware dedicated to YunoHost: laptop, nettop, netbook, desktop with 512MB RAM and 16GB capacity (at least)
  • A USB stick with at least 1GB capacity OR a standard blank CD
  • A reasonable ISP, preferably with a 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

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

If you wish to check the validity of our signed images, you can download our public key.

USB drive Flash the YunoHost image

Now that you downloaded the image of YunoHost, you should flash it on a USB stick or a CD/DVD.

Download Etcher for your operating system and install it.

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

Etcher

Boot the machine on your USB stick

  • Plug the ethernet cable (one side on your main router, the other on your server).
  • 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".

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

N.B.: 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.

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. For instructions, at the top of this page, select "Remote server", then "VPS or dedicated server with Debian".

Proceed with the initial configuration

If you are in the process of restoring a server using a YunoHost backup, you should skip this step and instead restore the backup instead of the postinstall step.

In an internet browser, type https://yunohost.local (or yunohost-2.local, and so on if multiple YunoHost servers are on your network).

If this doesn't work, you can look for the the local IP address of your server. The address typically looks like 192.168.x.y, and you should therefore type https://192.168.x.y in your browser's address bar.

During the first visit, you will very likely encounter a security warning related to the certificate used by the server. For now, your server uses a self-signed certificate. You will later be able to add a certificate automatically recognized by web browsers as described in the certificate documentation. For now, you should add a security exception to accept the current certificate. (Though, PLEASE, do not take the habit of blindly accepting this kind of security alert!)

You should then land on this page :

Initial configuration page

Preview of the Web initial configuration page
Main domain

This will be the domain used by your server's users to access the authentication portal. You can later add other domains, and change which one is the main domain if needed.

  • If you're new to self-hosting and do not already have a domain name, we recommend using a .nohost.me / .noho.st / .ynh.fr (e.g. homersimpson.nohost.me). Provided that it's not already taken, the domain will be configured automatically and you won't need any further configuration step. Please note that the downside is that you won't have full-control over the DNS configuration.

  • If you already own a domain name, you probably want to use it here. You will later need to configure DNS records as explained here.

Yes, you have to configure a domain name. If you don't have any domain name and don't want a .nohost.me / .noho.st / .ynh.fr either, you can set up a dummy domain such as yolo.test and tweak your local /etc/hosts file such that this dummy domain points to the appropriate IP, as explained here.

First user

Since YunoHost 11.1, the first user is now created at this stage. You should pick a username and a reasonably complex password. (We cannot stress enough that the password should be robust!) This user will be added to the Admins group, and will therefore be able to access the user portal, the web admin interface, and connect via SSH or SFTP. Admins will also receive emails sent to root@yourdomain.tld and admin@yourdomain.tld : these emails may be used to send technical informations or alerts. You can later add additional users, which you can also add to the Admins group.

This user replaces the old admin user, which some old documentation page may still refer to. In which case : just replace admin with your username.

Run the initial diagnosis

Once the postinstall is done, you should be able to actually log in the web admin interface using the credentials of the first user you just created.

The diagnosis system is meant to provide an easy way to validate that all critical aspects of your server are properly configured - and guide you in how to fix issues. The diagnosis will run twice a day and send an alert if issues are detected.

N.B. : don't run away ! The first time you run the diagnosis, it is quite expected to see a bunch of yellow/red alerts because you typically need to configure DNS records (if not using a .nohost.me/noho.st/ynh.fr domain), add a swapfile if not enough ram and/or port forwarding.

If an alert is not relevant (for example because you don't intend on using a specific feature), it is perfectly fine to flag the issue as 'ignored' by going in the webadmin > Diagnosis, and clicking the ignore button for this specifc issue.

To run a diagnosis, go on Web Admin in the Diagnosis section. Click Run initial diagnosis and you should get a screen like this :

Preview of the diagnostic panel

Get a Let's Encrypt certificate

Once you configured DNS records and port forwarding (if needed), you should be able to install a Let's Encrypt certificate. This will get rid of the spooky security warning from earlier for new visitors.

For more detailed instructions, or to lean more about SSL/TLS certificates, see the corresponding page here.

Go in Domains > Click on your domain > SSL Certificate

Preview of the diagnostic panel

Congratz!

You now have a pretty well configured server. If you're new to YunoHost, we recommend to have a look at the guided tour. You should also be able to install your favourite applications. Don't forget to plan backups !

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to suggest changes.