How to Install Homarr Dashboard with Docker on Ubuntu 24.04

Homarr is a self-hosted dashboard with a drag-and-drop editor. Unlike static start pages, it connects to your services through integrations and shows live data in widgets, and it can list and control Docker containers. In this tutorial you will install Homarr 1.x with Docker Compose on Ubuntu 24.04, publish it over HTTPS behind Nginx, create the administrator account, and build a board with apps, widgets and an integration.

Note

Homarr 1.x is a rewrite of the older 0.x releases and uses a new image, ghcr.io/homarr-labs/homarr. Guides that use ghcr.io/ajnart/homarr refer to the old version, whose configuration is not compatible.

Prerequisites

To follow this guide you need:

A server running Ubuntu 24.04 LTS with at least 1 GB of RAM, for example a CubePath VPS.
A non-root user with sudo privileges.
Docker Engine and the Docker Compose plugin installed from Docker's official repository.
A domain name with an A record pointing to your server. This guide uses dashboard.your_domain.
Ports 80 and 443 reachable from the internet.

Step 1 - Creating the directory and encryption key

Homarr stores its database, uploaded icons and settings in a single data directory. Create it:

sudo mkdir -p /opt/homarr/appdata
cd /opt/homarr

Homarr encrypts the credentials of your integrations (API keys, passwords) with a key you provide. It must be 64 hexadecimal characters. Generate it and save it in a .env file that Docker Compose reads automatically:

echo "SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32)" | sudo tee /opt/homarr/.env > /dev/null
sudo chmod 600 /opt/homarr/.env

Important

Keep a copy of this key with your backups. Without it, Homarr cannot decrypt the integration secrets stored in its database.

Step 2 - Writing the Docker Compose file

Create the Compose file:

sudo nano /opt/homarr/docker-compose.yml

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:7575:7575"
    environment:
      SECRET_ENCRYPTION_KEY: ${SECRET_ENCRYPTION_KEY}
    volumes:
      - ./appdata:/appdata
      - /var/run/docker.sock:/var/run/docker.sock

Two notes about this file:

Port 7575 is published only on 127.0.0.1. Ports published by Docker bypass UFW, so this keeps Homarr reachable only through Nginx.
Mounting /var/run/docker.sock enables the Docker integration. Access to the Docker socket is equivalent to root access on the host, so anyone with admin rights in Homarr can control your containers. If you do not need that feature, remove the line.

Validate and start the container:

sudo docker compose config --quiet && sudo docker compose up -d

Check that it is running and answers locally:

sudo docker compose ps
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:7575/

NAME              IMAGE                               SERVICE   STATUS          PORTS
homarr-homarr-1   ghcr.io/homarr-labs/homarr:latest   homarr    Up 20 seconds   127.0.0.1:7575->7575/tcp
307

The 307 is a redirect to the onboarding page, which means Homarr is up. If the container keeps restarting, run sudo docker compose logs homarr; a message about the encryption key means the value in .env is not 64 hexadecimal characters.

Step 3 - Configuring Nginx and HTTPS

Install Nginx and Certbot and open the web ports:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'

Homarr pushes live updates to the browser over WebSockets, so the proxy must forward the Upgrade headers. Create the server block:

sudo nano /etc/nginx/sites-available/homarr

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name dashboard.your_domain;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:7575;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        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;
    }
}

Enable the site, test the configuration and reload:

sudo ln -s /etc/nginx/sites-available/homarr /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Request a Let's Encrypt certificate. Certbot adds the TLS settings and a redirect from HTTP to HTTPS:

sudo certbot --nginx -d dashboard.your_domain

Step 4 - Completing the onboarding

Open https://dashboard.your_domain. Homarr starts an onboarding wizard:

Choose to start from scratch. The import option is only for migrating a configuration exported from Homarr 0.x.
Create the administrator account with a username and a strong password.
Review the initial settings, such as whether anonymous usage statistics are sent, and finish.

You are then logged in and taken to the management area. Since only the administrator exists, nobody else can sign in until you create more users.

Step 5 - Building your first board

Homarr organizes the dashboard in boards. Each board is a grid where you place apps (links to services) and widgets (live information).

First, register the services you want to link. Go to Management > Apps, create a new app, and fill in:

Name: for example Grafana.
Icon: search the built-in icon picker, which includes the Dashboard Icons collection, by typing the application name.
URL: https://grafana.your_domain.

Next, create a board in Management > Boards, open it, and switch to edit mode with the pencil icon. From there you can add items to the grid:

An App item that points to one of the apps you registered. App items can show a status indicator that turns red when the URL stops responding.
A Clock widget with your time zone.
A Weather widget for your location.
An RSS feeds widget with the feeds you follow.

Drag the items to arrange them, resize them from the corner, and leave edit mode to save. In the board settings you can make it your home board, change the background and colors, and decide whether it is visible to users who are not logged in.

Step 6 - Adding an integration

Integrations let widgets read data from your services. Homarr supports many of them, such as Pi-hole, AdGuard Home, Jellyfin, Plex, the *arr applications, qBittorrent, Proxmox and Home Assistant. As an example, to connect a Pi-hole server:

Go to Management > Integrations and add a new Pi-hole integration.
Enter the URL of the Pi-hole instance and the credential it asks for (an API key or password, depending on the Pi-hole version).
Use Test connection, then save.

Now edit your board, add the DNS Hole summary widget, and select the Pi-hole integration in its settings. The widget shows blocked queries and lets you pause blocking.

Integrations are queried by the Homarr server, not by your browser. The URL must therefore be reachable from inside the Homarr container. For a service running in another Compose project on the same host, either use its public URL or attach Homarr to that project's Docker network and use the container name, for example http://pihole:80.

Step 7 - Managing Docker containers

With the Docker socket mounted, Homarr lists the containers running on the host. Open Management > Tools > Docker to see each container with its image, state and ports. From this page you can start, stop, restart or remove containers without opening a terminal.

To confirm that Homarr can talk to Docker, check that the socket is visible inside the container:

sudo docker compose exec homarr ls -l /var/run/docker.sock

srw-rw---- 1 root 988 0 Sep 25 10:02 /var/run/docker.sock

Step 8 - Adding users and groups

To share the dashboard, go to Management > Users and create accounts for other people. Permissions are assigned to groups, not directly to users: create a group in Management > Groups, choose what its members can do (for example, view boards but not modify integrations), and add users to it. Board access can also be granted per user or group in each board's settings.

Homarr can also authenticate users against an LDAP directory or an OpenID Connect provider. These are configured with environment variables in the Compose file; the Homarr documentation lists the variables for each provider.

Step 9 - Backing up Homarr

All state lives in /opt/homarr/appdata. Stop the container briefly for a consistent copy, archive the directory together with the .env file, and start it again:

cd /opt/homarr
sudo docker compose stop
sudo tar -czf ~/homarr-backup-$(date +%F).tar.gz -C /opt/homarr appdata .env
sudo docker compose start

Troubleshooting

The dashboard loads but widgets never update, or the browser console shows WebSocket errors. The proxy is not forwarding the upgrade headers. Compare your server block with Step 3 and run sudo nginx -t && sudo systemctl reload nginx.

An integration test fails with a timeout. The Homarr container cannot reach the service URL. Test it from inside the container, for example sudo docker compose exec homarr wget -qO- http://pihole:80/admin/ | head -n 5, and fix the URL or the Docker network.

The Docker page is empty or shows an error. The socket is not mounted. Check the volumes section of the Compose file and run sudo docker compose up -d to recreate the container.

Conclusion

You have Homarr 1.x running on Ubuntu 24.04 behind Nginx with HTTPS, with a board of apps and widgets, a working integration and control over your Docker containers. Next, add integrations for the other services you run, create boards for different teams or purposes, and connect your identity provider through OpenID Connect so users sign in with their existing accounts.

On this page