Homarr Docker Dashboard: Organize Your Self-Hosted Services on a VPS

Core Architecture and System Requirements

To deploy Homarr successfully on a Virtual Private Server (VPS), ensure your environment meets the following specifications: - Operating System: Linux (Ubuntu 22.04 LTS or Debian 12 recommended) - Container Runtime: Docker Engine v24.0+ and Docker Compose v2.20+ - Resources: Minimum 1 CPU Core, 1 GB RAM, and at least 5 GB of free disk space. - Network: Port 7575 open on your VPS firewall (e.g., UFW or security groups) for dashboard access, plus standard ports 80 and 443 if using a reverse proxy.

Step 1: Directory Layout & File Initialization

Create a dedicated directory structure on your VPS to keep all configuration, data, and icon assets persistent.

mkdir -p ~/homarr/{appdata,icons}
cd ~/homarr

Generate a secure, random 64-character hexadecimal key for database encryption. This key encrypts sensitive credentials (like integration API keys) inside the Homarr database:

openssl rand -hex 32

Save the generated key. It will be passed as the SECRET_ENCRYPTION_KEY environment variable in the next step.

Step 2: Production-Ready Docker Compose Configuration

Create a file named docker-compose.yml under ~/homarr/:

version: '3.8'

services:
  homarr:
    container_name: homarr
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Mount read-only to query local container status
      - ./appdata:/appdata
      - ./icons:/app/public/icons
    environment:
      - SECRET_ENCRYPTION_KEY=YOUR_GENERATED_64_CHAR_HEX_KEY
      - PORT=7575
      - NODE_ENV=production

Volume Mapping Deep Dive

1. /var/run/docker.sock:/var/run/docker.sock:ro: Exposes the Docker daemon socket read-only to Homarr. This enables the Docker Integration, allowing Homarr to auto-discover containers, monitor CPU/Memory usage, and start/stop containers from the UI.
2. ./appdata:/appdata: Holds the local SQLite database, configuration files, user preferences, and dashboard layout structure.
3. ./icons:/app/public/icons: Stored directory for custom dashboard icons. By mapping this, you can drop .png or .svg icons here, and they will be immediately available in the UI.

Step 3: Deploying and Validating the Container

Bring up the stack in detached mode:

docker compose up -d

Verify that the container is running and listening on the correct port:

docker compose ps
docker compose logs -f homarr

If the logs show Server started on port 7575 without database errors, Homarr is running successfully.

Step 4: Configuring Reverse Proxy (Nginx) and SSL

To expose Homarr securely over HTTPS, configure Nginx as a reverse proxy and acquire a Let's Encrypt certificate using Certbot.

Create a new Nginx server block configuration at /etc/nginx/sites-available/homarr:

server {
    listen 80;
    server_name dashboard.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:7575;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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 configuration and reload Nginx:

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

Obtain a free SSL certificate:

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

Step 5: Post-Install Setup and Docker Integrations

Navigate to https://dashboard.yourdomain.com (or http://<VPS_IP>:7575 if accessing directly).

Admin Account Creation

On the first run, Homarr will prompt you to create an administrator account. Configure a secure password to protect the dashboard configuration menu.

Integrating the Docker Socket

Since the host's Docker socket is mapped into the container, Homarr can detect system health and running containers: 1. Go to Settings -> Integrations. 2. Click Add Integration and select Docker. 3. Set the endpoint to unix:///var/run/docker.sock. 4. Click Test connection and then Save. 5. Once saved, you can add the "Docker" widget to your workspace to view container memory/CPU metrics and manage state.

Adding Custom Apps and Widgets

1. Enter edit mode by clicking the Edit button in the top-right corner.
2. Click Add Item to create a tile for your services (e.g., Pi-hole, Plex, Portainer).
3. Configure the Address and upload an icon.
4. Drag and drop widgets like Weather, System Stats, or Calendar to build a unified system dashboard.