Deploy Homarr Dashboard

Log in to your VPS and get the system up to date:

apt update && apt upgrade -y

Create a non-root user and add it to the sudo group:

adduser deploy
usermod -aG sudo deploy

Configure the firewall:

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Switch to the new user:

su - deploy

Install Docker using the official convenience script:

curl -fsSL https://get.docker.com | sudo sh

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify the installation:

docker --version
docker compose version

Set up a clean directory structure:

mkdir -p ~/homarr/{configs,icons,data}
cd ~/homarr

Create the Compose file:

services:
  homarr:
    container_name: homarr
    image: ghcr.io/ajnart/homarr:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./configs:/app/data/configs
      - ./icons:/app/public/icons
      - ./data:/data
    ports:
      - "7575:7575"
    environment:
      - TZ=America/Chicago

Adjust TZ to match your timezone. The Docker socket mount gives Homarr read access to your running containers for live status display. Remove that line if you prefer not to expose the socket.

Pull the image and bring up the stack:

docker compose up -d

Confirm the container is running:

docker compose ps

At this point Homarr is accessible at http://YOUR_VPS_IP:7575.

Install Nginx:

sudo apt install nginx -y
sudo systemctl enable nginx
sudo systemctl start nginx

Create a server block for your Homarr subdomain:

server {
    listen 80;
    listen [::]:80;
    server_name dashboard.yourdomain.com;

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

Enable the site and test configuration:

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

Install Certbot and the Nginx plugin:

sudo apt install certbot python3-certbot-nginx -y

Request a certificate for your domain:

sudo certbot --nginx -d dashboard.yourdomain.com

Verify automatic renewal is active:

sudo systemctl status certbot.timer
sudo certbot renew --dry-run

Open https://dashboard.yourdomain.com in your browser. On first launch, Homarr presents an onboarding screen where you can:

• • Name your dashboard
• • Choose a default layout (default, compact, or minimal)
• • Set your color theme and background

Adding Your First Tiles

Click the pencil (edit) icon in the top-right corner to enter edit mode. Common integrations that work well:

• • Docker - shows live container status
• • Sonarr / Radarr / Prowlarr - media automation
• • Portainer - container management UI
• • Uptime Kuma - uptime monitoring
• • Dashdot - live server stats widget

Enabling Authentication

Navigate to Settings → Security and enable the built-in username/password authentication. Set a strong password before exposing the dashboard to the internet.

To pull the latest image and restart the container:

cd ~/homarr
docker compose pull
docker compose up -d

Your configuration persists across updates because it is stored in the bind-mounted directories on the host.

Once Nginx is handling traffic, block direct access to port 7575:

sudo ufw deny 7575/tcp

All traffic should now flow through Nginx on port 443.