Homarr Server Dashboard Installation

Homarr is a modern, interactive server management dashboard that goes beyond static dashboards by integrating directly with Docker containers, *arr apps, media servers, and other self-hosted services to display live widgets and status information. With a drag-and-drop interface, built-in Docker integration, and a growing library of widgets, Homarr provides a dynamic command center for your self-hosted infrastructure.

Prerequisites

  • Docker and Docker Compose installed
  • Root or sudo access
  • Other self-hosted services to monitor (optional but recommended)
  • A domain name for HTTPS access (optional)

Installing Homarr with Docker

# Create Homarr directory
sudo mkdir -p /opt/homarr/{configs,icons,data}

# Create docker-compose.yml
sudo tee /opt/homarr/docker-compose.yml <<'EOF'
version: '3.8'

services:
  homarr:
    image: ghcr.io/ajnart/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # Docker integration
      - /opt/homarr/configs:/app/data/configs
      - /opt/homarr/icons:/app/public/icons
      - /opt/homarr/data:/data
    environment:
      - BASE_URL=https://dashboard.example.com
      - SECRET_ENCRYPTION_KEY=your-32-char-secret-here  # Change!
      - AUTH_SESSION_EXPIRY_TIME=30d
      - NEXTAUTH_URL=https://dashboard.example.com
      - NEXTAUTH_SECRET=your-nextauth-secret-here       # Change!
EOF

# Generate secrets
ENCRYPTION_KEY=$(openssl rand -hex 16)
NEXTAUTH_SECRET=$(openssl rand -hex 32)
sed -i "s/your-32-char-secret-here/${ENCRYPTION_KEY}/" /opt/homarr/docker-compose.yml
sed -i "s/your-nextauth-secret-here/${NEXTAUTH_SECRET}/" /opt/homarr/docker-compose.yml

# Start Homarr
cd /opt/homarr
sudo docker compose up -d

sudo docker compose logs -f homarr

Access Homarr at http://your-server:7575.

Create admin account on first visit:

  1. Navigate to http://your-server:7575
  2. Click Create an account
  3. Set username and password
  4. The first account is automatically an admin

Initial Setup and Layout

Dashboard layout uses a tile-based grid system:

  1. Click the Edit button (pencil icon) to enter edit mode
  2. Drag and resize tiles to your preferred layout
  3. Click + to add new widgets or service links
  4. Click the Save button when finished

Add a service link:

  1. In edit mode, click + Add tile
  2. Select App (service link) from the tile menu
  3. Configure:
    • App name: Grafana
    • URL: https://grafana.example.com
    • Icon: Upload or select from icon library
    • Description: Metrics dashboards
  4. Click Save

Create multiple boards:

  1. Click the + icon next to the board selector
  2. Name the new board (e.g., "Media", "DevOps", "Home")
  3. Switch between boards using the top navigation

Widget Configuration

Homarr provides interactive widgets that pull live data from your services:

Weather widget:

# In the widget configuration dialog:
Widget type: Weather
Location: New York, US (or coordinates)
Show city: true
Show forecast: true
Temperature unit: Celsius

Date/Time widget:

Widget type: Date and Time
Timezone: America/New_York
Format 24h: true
Show seconds: false

RSS Feed widget:

Widget type: RSS
URL: https://www.theregister.com/headlines.atom
Max items: 5
Title: Tech News

System stats widget (requires integration):

Widget type: System Stats
# Shows CPU, memory, and disk usage
# Requires the Glances integration or similar

Docker Integration

Homarr reads from the Docker socket to show container status:

# Verify Docker socket is mounted
sudo docker compose exec homarr ls /var/run/docker.sock

# Homarr automatically discovers containers
# Each container shows with its running/stopped status

Enable Docker integration in settings:

  1. Go to Settings > Integrations
  2. Under Docker, enable Docker socket
  3. Socket path: /var/run/docker.sock

Add a Docker widget to your board:

  1. In edit mode, click + Add tile
  2. Select Docker widget
  3. Choose which containers to display
  4. Filter by label: add homarr.enable=true label to containers you want shown
# Add Homarr labels to your other docker-compose.yml files:
services:
  jellyfin:
    labels:
      - "homarr.enable=true"
      - "homarr.name=Jellyfin"
      - "homarr.icon=https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/Jellyfin/icon.png"
      - "homarr.group=Media"
      - "homarr.url=https://jellyfin.example.com"

Docker container actions from the dashboard:

  • Start / stop containers directly from the Docker widget
  • View container logs (click the log icon)
  • Restart containers without opening Portainer

Service Monitoring

Ping/HTTP health checks:

# Add to any service link:
Service URL: https://grafana.example.com
Status check: HTTP   # or: Ping, DNS
Status check URL: https://grafana.example.com/api/health

*Integration with arr apps (Sonarr, Radarr, etc.):

  1. Go to Settings > Integrations
  2. Click Add integration
  3. Select Sonarr
  4. Enter:
    • URL: http://sonarr:8989
    • API Key: (from Sonarr Settings > General)
  5. Save and add a Sonarr widget to display queue stats

Available integrations:

IntegrationShows
SonarrTV download queue, upcoming episodes
RadarrMovie download queue
JellyfinActive streams, library size
qBittorrentDownload/upload speeds
NZBGetDownload queue
Pi-holeBlocked queries count
ProxmoxVM/container status
NextcloudStorage usage
OverseerrPending requests

User Management

User roles:

  • Admin: Full access, can modify layout and settings
  • User: Can view dashboards but cannot edit layout
  • Guest: Read-only access (if enabled)

Create a new user:

  1. Go to Settings > Users
  2. Click Invite new user or Create user
  3. Set username, email, and initial password
  4. Assign role (Admin/User)

Enable guest access:

# In docker-compose.yml environment:
- DISABLE_AUTH=false            # Keep auth enabled
- AUTH_ENABLE_GUEST_MODE=true   # Allow guest viewing

LDAP/OIDC authentication:

# Environment variables for OIDC
- AUTH_PROVIDER=oidc
- AUTH_OIDC_URI=https://auth.example.com/.well-known/openid-configuration
- AUTH_OIDC_CLIENT_ID=homarr
- AUTH_OIDC_CLIENT_SECRET=your-oidc-secret
- AUTH_OIDC_SCOPE_OVERWRITE=openid email profile

Customization and Themes

Switch between light and dark mode:

  • Click the sun/moon icon in the top navigation bar
  • Or set default in Settings > Appearance

Background image:

  1. Go to Settings > Appearance
  2. Upload a background image
  3. Set blur and opacity for overlay effect

Custom CSS:

# Settings > Appearance > Custom CSS
# Example: adjust card transparency
.dashboard-tile {
  background-color: rgba(255, 255, 255, 0.85) !important;
  backdrop-filter: blur(10px);
}

Nginx reverse proxy:

server {
    listen 443 ssl;
    server_name dashboard.example.com;

    ssl_certificate /etc/letsencrypt/live/dashboard.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dashboard.example.com/privkey.pem;

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

Troubleshooting

Cannot connect to integrations:

# Verify container networking — Homarr needs to reach other containers
# Use Docker service names for containers on the same network:
# http://jellyfin:8096 (not http://localhost:8096)

# Or add Homarr to the same Docker network:
docker network connect media_default homarr

# Test connectivity from inside the Homarr container
sudo docker compose exec homarr wget -q -O - http://jellyfin:8096

Widget data not updating:

# Check Homarr logs for API errors
sudo docker compose logs homarr | grep -i error

# Verify API key is correct by testing directly
curl -H "X-Api-Key: your-api-key" http://sonarr:8989/api/v3/system/status

# Restart Homarr to clear cache
sudo docker compose restart homarr

Layout not saving:

# Check config directory permissions
ls -la /opt/homarr/configs/
sudo chown -R 1000:1000 /opt/homarr/configs/

# Verify sufficient disk space
df -h /opt/homarr/

Conclusion

Homarr elevates the concept of a server dashboard from a static bookmark list to a dynamic service monitoring platform with live Docker status, service integrations, and interactive widgets that surface important information at a glance. Its drag-and-drop interface and deep integration with popular self-hosted applications make it an excellent operational hub for managing complex multi-service VPS deployments without navigating between multiple admin interfaces.