Install YunoHost

Select the hardware on which you want install YunoHost :


  • A Raspberry Pi zero
  • A power supply (either an adapter or a MicroUSB cable) for your board;
  • A microSD card: 16GB capacity (at least), class "A1" highly recommended (such as this SanDisk A1 card);
  • A reasonable ISP, preferably with a good and unlimited upstream bandwidth
  • An usb OTG or a wifi dongle to connect your Raspberry Pi Zero
  • A computer to read this guide, flash the image and access your server.
  • Download the YunoHost image

    microSD card with adapter Flash the YunoHost image

    Now that you downloaded the image of YunoHost, you should flash it on a microSD card

    Download Etcher for your operating system and install it.

    Plug your SD card, select your image and click "Flash"


    Power up the board

    • Plug the ethernet cable (one side on your main router, the other on your board).
      • For advanced users willing to configure the board to connect to WiFi instead, see for example here.
    • Plug the SD card in your board
    • (Optional) You can connect a screen+keyboard directly on your board if you want to troubleshoot the boot process or if you're more comfortable to "see what happens" or want a direct access to the board.
    • Power up the board
    • Wait a couple minutes while the board autoconfigure itself during the first boot
    • Make sure that your computer (desktop/laptop) is connected to the same local network (i.e. same internet box) as your server.

    Connect to the board and hotfix the image

    Raspberry Pi 1 and 0 are not totally supported due to compilation issues for this architecture.

    However, it is possible to fix by yourself the image before to run the initial configuration.

    To achieve this, you need to connect on your raspberry pi as root user via SSH with the temporary password yunohost:

    ssh root@yunohost.local

    (or yunohost-2.local, and so on if multiple YunoHost servers are on your network)

    Then run the following commands to work around the metronome issue:

    mv /usr/bin/metronome{,.bkp}   
    mv /usr/bin/metronomectl{,.bkp} 
    ln -s /usr/bin/true /usr/bin/metronome
    ln -s /usr/bin/true /usr/bin/metronomectl

    And this one to work around the upnpc issue:

    sed -i 's/import miniupnpc/#import miniupnpc/g' /usr/lib/moulinette/yunohost/

    This last command need to be run after each yunohost upgrade :/

    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 / / (e.g. 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 / / either, you can set up a dummy domain such as yolo.test and tweak your /etc/hosts file such that this dummy domain points to the appropriate IP, as explained here).

    Administration password

    This password will be used to access to your server's administration interface. You will also use it to connect via SSH or SFTP . In general terms, this is your system's key, choose it carefully!

    Create a first user

    Once the postinstall is done, you should be able to actually log in the web admin interface using the administration password.

    So far, your server now has an admin user - but admin is not a "regular" user and can't be used to log on the user portal.

    Let's therefore add a first "regular" user.

    The first user you create is a bit special : it will receive emails sent to root@yourdomain.tld and admin@yourdomain.tld. These emails may be used to send technical informations or alerts.

    Go in Users > Add

    User creation

    Preview of the user creation UI

    Run the initial diagnosis

    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 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. 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 a Let's Encrypt certificate. This will get rid of the spooky security warning from earlier for new visitors.

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

    Preview of the diagnostic panel


    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 !

    ¿Encontraste errores? ¿Crees que puedes mejorar esta documentación? Simply click the Edit link at the top of the page, and then the icon on Github to suggest changes.