Install & Configure YunoHost on Debian

YunoHost is a Debian-based open-source platform / operating system that aims to democratize self-hosting by providing seamless installation and configuration of self-hosted web-applications including the likes of NextCloud, Flarum, GitLab, Ghost, Syncthing, and even full-fledged WordPress sites. Once installed, YunoHost provides you with a secure, …

YunoHost is a Debian-based open-source platform / operating system that aims to democratize self-hosting by providing seamless installation and configuration of self-hosted web-applications including the likes of NextCloud, Flarum, GitLab, Ghost, Syncthing, and even full-fledged WordPress sites.

Once installed, YunoHost provides you with a secure, yet, simple GUI to configure settings, create users, and self-host applications from its app marketplace, and a clean frontend UI that acts as a homepage for all of your applications.

In this tutorial, we’ll install and configure YunoHost on a server running Debian 10 (Buster), you can also install it on a Raspberry Pi or a VirtualBox.

YunoHost has started transitioning to Debian 11 (Bullseye), but it’s still in its Alpha-stage testing at the time of writing, I’ll update this tutorial once a stable release is available.

Alright, let’s get into it.

Step 1: Creating a Virtual Machine

Any basic virtual machine running Debian 10 (Buster) will suffice:

  • 1 GB RAM
  • 1 vCPU
  • 20 GB Storage

Although, you’ll need to increase RAM, CPU, and Storage depending on the applications you’ll be installing, pick a server location accordingly.

I’ll be using a Debian 10 VM on Linode, you can follow the same steps on any other cloud service provider.

Step 2: Configuring the Virtual Machine for YunoHost

Now, let’s configure our server:

Step 2.1: Connect to the Server via SSH

Open up the terminal on your device, and run this command:

ssh root@123.45.67.89

If you chose a username while creating the virtual machine, use that instead of root, and replace 123.45.67.89 with the IP address of your VM.

You’ll be prompted with “The authenticity of host…”, just type yes, and then enter the password.

Step 2.2: Configure Automatic Updates

Let’s update packages and configure automatic updates so that our server gets patched automatically.

# Update packages
sudo apt update && apt upgrade

# Install unattended-upgrades
sudo apt install unattended-upgrades

# Configure unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades

# Test unattended-upgrades
sudo unattended-upgrades --dry-run --debug

Step 2.3: Creating a “sudo” user

If your cloud provider didn’t ask you to choose a username while creating it, you are given root access to your server; it is recommended to not use the “root” user, which has unlimited privileges and can execute any command, even ones that could potentially disrupt your server.

Let’s create a new user on a server that can use “sudo” to do day-to-day administration tasks.

# Create a new user
adduser username

# Add user to the "sudo" group
usermod -aG sudo username

# Check user's group
groups username

# Switching users
su - username
su - root

Step 2.4: Configure SSH Keys

Using SSH keys instead of passwords provides you with better security, as SSH keys are far more long and complex than any password could ever be; you can also add an extra password to the SSH keys, requiring both the SSH key and the password to access the server.

Log out of the server or just open up a new terminal on your computer to create SSH keys:

# Create ssh keys
ssh-keygen -b 4096 

# View ssh keys
ls -l ~/.ssh

# Add public key to server
ssh-copy-id -i ~/.ssh/keyname.pub username@123.45.67.89

# Switch ssh keys on client
ssh-add ~/.ssh/keyname

During the ssh-keygen process, you’ll be prompted for file location, use the default one or give a new location by typing in /home/username/.ssh/keyname, and enter a strong password for the SSH key.

In the .ssh folder, there’ll be two files, the one with “.pub” extension is your public key, the other one is your private key, never share the private key with anyone.

You might get a message like Could not open a connection to your authentication agent when switching SSH keys, you’ll need to start ssh-agent first using:

eval `ssh-agent`

Once done, you can log in to the server by just using the ssh username@123.45.67.89 command without entering the user password, although you will need to enter the password of your SSH key.

Step 2.5: Disable root login

Now that we have a new user with limited privileges that can run “sudo” commands and can access the server via SSH keys; let’s lock down our root user, as it is usually the most targeted account by hackers.

To do so, type in sudo nano /etc/ssh/sshd_config, and update PermitRootLogin to no and add AllowUsers username as shown below:

Disable root login via SSH

Optionally, you can also go ahead and disable password-based login via SSH for all users, including the new user account we just created, by updating these values in the same sshd config file:

# Disable password-based login via ssh for all users [optional]
PasswordAuthentication no
ChallengeResponseAuthentication no

Once done, save the file using Ctrl + O & Ctrl + X, and restart the sshd service using this command:

sudo systemctl restart sshd

Now, your server is ready to install the YunoHost, let’s get into it.

Step 3: Installing YunoHost

We’ll be using the official YunoHost script to install YunoHost on our Debian server, it takes care of all the configuration, and you’ll have your YunoHost server up and running in minutes.

Step 3.1: Download & Run YunoHost Script

To download the script, we’ll need curl, install it if it doesn’t come with your installation:

sudo apt install curl

Next up, download and run the YunoHost server script using:

curl https://install.yunohost.org | sudo bash

You’ll be prompted to overwrite configuration files, just select Yes.

Overwrite Configuration Files Prompt: Select “Yes”

Once done, you’ll be greeted with something like this:

[INFO] Installation logs are available in /var/log/yunohost-installation_20220131_134910.log
[ OK ] YunoHost installation completed !
===============================================================================
You should now proceed with Yunohost post-installation. This is where you will
be asked for :
  - the main domain of your server ;
  - the administration password.

You can perform this step :
  - from the command line, by running 'yunohost tools postinstall' as root
  - or from your web browser, by accessing :
    - https://123.45.67.89/ (global IP, if you're on a VPS)

If this is your first time with YunoHost, it is strongly recommended to take
time to read the administator documentation and in particular the sections
'Finalizing your setup' and 'Getting to know YunoHost'. It is available at
the following URL : https://yunohost.org/admindoc
===============================================================================

Step 3.2: YunoHost Post-install Configuration

Now, we’ll need to do initial configuration of our YunoHost instance, you can skip this step if you want to restore a previous YunoHost backup.

You can do the post-install configuration either via the command line or by typing in the IP address of your server in the address bar of your web browser.

To do it via the command line:

sudo yunohost tools postinstall

You’ll be asked to enter the main domain, enter the domain name you want to use to access the YunoHost instance.

Next up, choose a strong administrative password for your YunoHost instance, and you’ll be greeted with something like this:

Success! YunoHost is now configured
Warning: The post-install completed! To finalize your setup, please consider:
    - adding a first user through the 'Users' section of the webadmin (or 'yunohost user create <username>' in command-line);
    - diagnose potential issues through the 'Diagnosis' section of the webadmin (or 'yunohost diagnosis run' in command-line);
    - reading the 'Finalizing your setup' and 'Getting to know YunoHost' parts in the admin documentation: https://yunohost.org/admindoc.

You have now installed YunoHost on your server, we need to log in to our fresh YunoHost instance to configure and manage domains.

Step 4: Configuring DNS for YunoHost

Now that we have YunoHost installed, we can access the admin panel by entering the IP address of the VM or the domain name in the address bar.

Let’s set up all the DNS configurations for our YunoHost instance, YunoHost provides a recommended DNS configuration, available via:

  • The web admin: Domain > yuno.example.com > DNS configuration;
  • The command line: sudo yunohost domain dns-conf yuno.example.com

If you tried entering the IP address or the domain name in the address bar, you might get a warning like this:

Just click on Advanced and Accept the Risk and Continue, your browser shows you this error because our server is using a self-signed SSL certificate, we’ll remedy this issue in the later section by installing a Let’s Encrypt SSL certificate.

YunoHost Admin Panel

From the admin panel, navigate to the Domains section, select your domain name, and click on the DNS Configuration button to access the recommended DNS configurations.

Here’s a simplified version of the recommended DNS configuration:

  • Create two new A records:
    • Enter @ for the host section, enter the IP address in value section, and update TTL to 3600.
    • Enter * for the host section, enter the IP address in value section, and update TTL to 3600.
  • Create two new SRV records:
    • Enter _xmpp-client._tcp for the host, 5222 for the port, 0 for priority, 5 for the weight, and update the TTL to 3600.
    • Enter _xmpp-server._tcp for the host, 5269 for the port, 0 for priority, 5 for the weight, and update the TTL to 3600.

You’ll need to append the subdomain to host if you are using a subdomain, example: _xmpp-client._tcp.yuno for yuno.example.com, update according to the DNS configuration that your YunoHost instance provides.

  • Create three new CNAME records:
    • Enter muc for the host, @ in target section, and set the TTL to 3600.
    • Enter pubsub for the host, @ in target section, and set the TTL to 3600.
    • Enter vjud for the host, @ in target section, and set the TTL to 3600.

Again, you’ll need to append the subdomain to host if you are using a subdomain, example: muc.yuno for yuno.example.com, update according to the DNS configuration that your YunoHost instance provides.

For your Mail configuration, create the following records:

  • An MX record with @ for the host, your domain name for the mail server with a priority of 10 and the TTL at 3600.
  • Three new TXT records:
    • Copy the TXT string, including the double quotes, from the sample zone file into the value box that starts with: "v=spf1", add @ to the hostname, and set the TTL at 3600.
    • Copy the long TXT string, including the double quotes, from the sample zone file into the value box, add mail._domainkey to the hostname, and set the TTL at 3600.
    • Copy the TXT string, including the double quotes, from the sample zone file into the value box, something like: "v=DMARC1; p=none", add _dmarc to the hostname, and set the TTL at 3600.

And finally, for Let’s Encrypt, configure the following record:

  • Create a new CAA record:
    • Enter @ for the hostname, set tag to issue, flags to 128, and set the TTL to 3600.

YunoHost also has a guide on DNS configuration.

The YunoHost Project provides a free and automatically configured domain name service as part of their initiative to make self-hosting more accessible, the following (sub)domains are being offered as of now:

  • whateveryouwant.nohost.me
  • whateveryouwant.noho.st
  • whateveryouwant.ynh.fr

You won’t have to do any of that if you chose to use a subdomain provided by YunoHost project, everything is configured automatically.

Step 5: Configuring SSL Certificate from Let’s Encrypt

Now that you have updated all DNS records, let’s configure an SSL certificate via Let’s Encrypt, ensuring that our connection to the site is secured by encrypted HTTPS.

YunoHost includes a function to install Let’s Encrypt to your domain through the admin panel, navigate to the Domains section, select your domain name, and click on the SSL Certificate.

Click on Install a Let’s Encrypt certificate button under Operations section, it might be grayed out, wait for DNS propagation to happen and try later.

Once an SSL certificate is configured, you won’t see the warning messages when you visit your domain or IP address of the YunoHost Instance

The Let’s Encrypt certificate will automatically renew by default. To manually renew your Let’s Encrypt certificate or revert to a self-signed certificate in the future, you can find options for same under the Operations section.

Step 6: Creating a First User

Alright, you’ll need to create a user who can access the applications and other services on your YunoHost server.

You can create a new user by navigating to Users section and clicking on New User.

Create New User for YunoHost Applications

The user panel can be accessed via the User interface button on top-right corner or by going to the URL: https://yuno.example.com/yunohost/sso or IP address: https://123.45.67.89/yunohost/sso

Step 7: Running Initial Diagnosis

Let’s run an initial diagnosis before we go ahead and install applications on our server, the diagnosis will help you ensure that everything is configured correctly and will guide you in fixing any issues.

Don’t panic, the first time you run the diagnosis, you’ll see a bunch of yellow/red alerts if your DNS has not been updated.

You’ll find a few errors that just aren’t relevant, click on the ignore button, if you don’t want to be notified about it.

Step 8: Installing Applications

YunoHost comes with a number of pre-packaged web applications in its catalog that can be installed on your server, it can be accessed by navigating to the Applications and clicking on the Install button.

YunoHost Application Catalog

You can either search for the apps you want to install, or pick one from the different categories, you can also install any custom apps by adding the URL in the Install custom app section.

YunoHost Maintenance & Conclusion

The YunoHost instance can be updated from the admin panel by navigating to System Update section, the Diagnosis page can provide you with insights about your server, check out YunoHost documentation for additional information

That’s all folks!

I’ll be soon updating this tutorial with the latest release and guides on backing up the server and more.

Leave a Comment