Learn how to set up Homarr, a powerful dashboard for your self-hosted services, on an Ubuntu 24.04 server. How to centralize and manage all your applications.
What is Homarr?
Our self-hosted applications, from media servers to productivity tools, are often scattered across different ports and subdomains. Homarr simplifies this by acting as a centralized dashboard, giving us a beautiful, easy-to-manage entry point for all our services. In this guide, we'll walk through the process of setting up Homarr as a Docker service on an Ubuntu 24.04 server, securing it with Nginx and a free SSL certificate from Certbot.
Prerequisites
To embark on this journey, we'll need a few things:
- An Ubuntu 24.04 LTS dedicate server or KVM VPS
- Root or Sudo Privileges
- A Domain name pointing A record to server IP
- Basic Command Line Knowledge
1. Getting the Server Ready
Before we dive into the installation, we need a clean Ubuntu 24.04 server. We'll be using Docker to containerize our services, which is a modern and efficient way to manage applications. We'll also be using docker-compose to define and run our multi-container application with a single command.
First, let's update our system's package list and install the necessary dependencies:
sudo apt update && sudo apt upgrade -y
2: Install Docker and Docker Compose
Listmonk is designed to run efficiently in Docker containers, making deployment straightforward and consistent. We'll install Docker Engine and Docker Compose.
Install Docker Engine:
Add Docker's official GPG key:
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
Add the repository to Apt sources:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
Install Docker packages:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
Verify Docker Installation:
sudo systemctl status docker
We should see "active (running)" in the output.
3. Deploying Homarr with Docker Compose
Docker Compose is a fantastic tool that lets us define a complete application stack in a single YAML file. This makes deployment and management incredibly simple. We'll create a docker-compose.yml file to run Homarr and define its network settings.
Let's create a directory for our Homarr configuration and then create the docker-compose.yml file within it.
mkdir -p ~/homarr && cd ~/homarr
We need to generate a SECRET_ENCRYPTION_KEY. We can do this with the openssl command.
openssl rand -hex 32
Create docker-compose.yml file:
nano ~/homarr/docker-compose.yml
Now, paste the following content into the file. Be sure to replace <your-path> with an absolute path on your server, like /opt/homarr. This path will be used to store Homarr's configuration, so our data will persist even if we update the container.
Copy the output and use it to replace your_64_character_hex_string in the file. This key is crucial for securing your dashboard settings and user data.
services:
homarr:
image: ghcr.io/homarr-labs/homarr:latest
container_name: homarr
restart: unless-stopped
ports:
- '7575:7575'
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- /home/yourusername/homarr/appdata:/appdata
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- SECRET_ENCRYPTION_KEY=f01a51828b152ff0b00c5429c29194f9fd9d094e65f7501ce7321ebeb410d7df
Note: Replace /home/yourusername/homarr/ this directory path with your directory path.
Save and close the file by pressing Ctrl + X, then Y, and then Enter.
With the file in place, navigate to the directory and start the Homarr container in detached mode (in the background):
docker compose up -d
You can now access Homarr by navigating to http://<your-server-ip>:7575 in your browser.
Troubleshoot
If you still facing issue 500 error, check the docker logs.
docker ps
Copy the container ID
docker logs <container ID>
If you get error something like:
mkdir: can't create directory '/appdata/db': Permission denied
mkdir: can't create directory '/appdata/redis': Permission denied
First check the directory is created or not. If not, create directory. If directory exists, than change the ownership:
docker compose down
sudo chown -R 1000:1000 /home/yourusername/homarr/appdata
docker compose up -d
4. Setting Up Nginx as a Reverse Proxy
While our dashboard is now accessible, we don't have a secure connection. To secure our site and use a custom domain, we'll configure Nginx as a reverse proxy. This will route traffic from our domain to the Homarr container.
First, let's install Nginx on our server:
sudo apt install nginx -y
Configure our firewall to allow HTTP and HTTPS traffic:
sudo ufw allow 'Nginx Full'
sudo ufw reload
Now, we'll create a new Nginx configuration file for Homarr. This file will define how Nginx handles requests for our domain.
sudo nano /etc/nginx/sites-available/homarr.conf
Add the following configuration. Be sure to replace homarr.yourdomain.com with our actual domain name.
server {
listen 80;
server_name homarr.yourdomain.com;
location / {
proxy_pass http://localhost:7575;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
Save and exit the file. Now, we need to create a symbolic link from sites-available to sites-enabled to activate the configuration.
sudo ln -s /etc/nginx/sites-available/homarr.conf /etc/nginx/sites-enabled/
We should now test our Nginx configuration for syntax errors and restart the service to apply the changes.
sudo nginx -t
sudo systemctl restart nginx
At this point, you should be able to access Homarr by navigating to http://homarr.yourdomain.com.
6. Securing Our Dashboard with Certbot and Let's Encrypt
To add SSL encryption and serve our site over HTTPS, we'll use Certbot, a free and open-source tool that automates the process of obtaining and renewing SSL certificates from Let's Encrypt.
First, install Certbot and the Nginx plugin:
sudo apt install certbot python3-certbot-nginx -y
With the plugin installed, we can now run Certbot to automatically configure Nginx and get our SSL certificate.
sudo certbot --nginx -d homarr.yourdomain.com
Certbot will ask for an email address and have us agree to the terms of service. It will then automatically find our Nginx configuration and modify it to include the SSL certificate. Once it's finished, it will output a success message.
We should now be able to access our Homarr dashboard securely at https://homarr.yourdomain.com. Certbot also automatically sets up a cron job to renew the certificate before it expires, ensuring our connection remains secure without any manual intervention.
