On top of Debian
YunoHost is easily installable on Debian !
This can be useful if you already have a Debian machine or can't use the recommended methods.
Get Debian
You should download the version Bookworm (Debian 12) and select the architecture for your PC.
When in doubt, select amd64, or i386 for a pre-2010 PC.
Debian Download pageAlternatively, you can browse the Debian archive for the latest 12.x version, select your architecture, the select iso-cd and download the netinst iso.
Installation
You might want to wipe the hard drive before starting the Debian installer.
Burn the iso to your USB key, for example using Etcher.
Debian installer will ask for a hostname and a domain name. You can use yunohost and yunohost.local. It is not that important since the YunoHost Installer will overwrite those anyway.
Debian will ask for a root password, which should be reaonably complex as it is your primary defense to possible attacks.
The installer will also ask for a user account and another password.
IMPORTANT: this username should be DIFFERENT from the first YunoHost user which you will choose during YunoHost's posinstall… For example, you can name it debian. Be sure to also use a long complex password.
When the install asks where to install and how to create disk partitions, select the option to use the whole disk, unless you know what you're doing.
- We recommend not to separate the
/home,/varor/tmppartitions. Use the option to “keep all files in one partition”. - If you don't know what you're doing, don't encrypt the disk (Decryption at power-on will be an issue)
The installer will ask about mirrors. Select a country and server close to your location, or use the default options.
The installer will ask which desktop environment you want. This is generally useless and might waste resources.
- Unselect all desktop environment
- Keep “standard system utilities” checked
After installing Debian
- Remove the installation media (unplug the USB stick)
- Reboot
- Login as
root - Install curl by typing
apt install curl
Run the install script
- Open a command line prompt on your server (either directly or through SSH)
- Make sure you are root (or type
sudo -ito become root) - Run the following command:
curl https://install.yunohost.org | bash
You might need to first install curl and ca-certificates by running:
apt install curl ca-certificates
Always ensure there's an s at the end of https.
For advanced users concerned with the curl | bash approach: consider reading "Is curl|bash insecure?" on Sandstom's blog, and possibly this discussion on Hacker News.
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.
This documentation assumes you're on the same local network as your YunoHost installation. Find out its IP address before continuing.
For a VPS, please use the public IP address instead of the local domain or address.
- From the web interface
- From the command line
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:
You can also perform the postinstallation with the command yunohost tools postinstall directly on the server, or via SSH.
Main domain
WSL specific configuration
You will have to choose a fake domain, since it will not be accessible from outside.
For example, ynh.wsl. The tricky part is advertising this domain to your host.
Alter your C:\Windows\System32\drivers\etc\hosts file. You should have a line starting by ::1, update it or add it if needed to get:
::1 ynh.wsl localhost
If you want to create subdomains, do not forget to add them in the hosts file too:
::1 ynh.wsl subdomain.ynh.wsl localhost
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
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.
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 as well as port forwarding on your home's router.
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.
Especially, installations on WSL or virtual machines will likely not be reachable from outside without further network configuration on Virtualbox and your machine.
- (Recommended) From the web interface
- From the command line
To run a diagnosis, go on Web Admin in the Diagnosis section. Click Run initial diagnosis and you should get a screen like this:
yunohost diagnosis run
yunohost diagnosis show --issues --human-readable
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.
- From the web interface
- From the command line
Go in Domains > Click on your domain > SSL Certificate
yunohost domain cert install
🎉 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 !