Self-Hosting Homarr: Customizable Server Dashboard with Integrations

Your homelab is growing. You’ve got Jellyfin, Sonarr, Radarr, Pi-hole, maybe a dozen more services scattered across different ports. Bookmarks aren’t cutting it anymore. You need a dashboard — but not one that requires hand-editing YAML files every time you add a service.

Homarr is a modern, highly customizable dashboard for your self-hosted services. Its killer feature: everything is configured through a drag-and-drop web UI. No config files, no YAML, no restarts. Add apps, rearrange widgets, configure integrations — all from your browser.

Why Homarr?

Choose Homarr if you want a visual editor, built-in auth, and deep integrations without touching config files. Choose Homepage if you prefer YAML-as-code, minimal resources, and maximum widget variety.

Prerequisites

• Docker and Docker Compose installed
• At least 500MB RAM available
• ~600MB disk space for the image
• Linux amd64 or arm64 (Raspberry Pi 4+ works great)

Docker Compose Setup

mkdir -p ~/homarr && cd ~/homarr

Create a docker-compose.yml:

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - ./appdata:/appdata
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - TZ=America/New_York
      - SECRET_ENCRYPTION_KEY=your-random-32-char-secret-here

Generate a proper encryption key:

openssl rand -hex 16

Use that output as your SECRET_ENCRYPTION_KEY. This encrypts sensitive data like integration credentials stored in Homarr’s database.

Start it up:

docker compose up -d

Visit http://your-server:7575 to access Homarr.

First-Time Setup

On first launch, Homarr will ask you to create an admin account. Pick a strong password — this protects access to your entire dashboard and any integration credentials you add later.

Once logged in, you’ll see an empty board. This is your canvas. Everything from here is drag and drop.

Adding Your First App

1. Click the + Add button in the top toolbar
2. Select App
3. Fill in the name (e.g., “Jellyfin”), URL, and pick an icon from the built-in library
4. Optionally add a description and set the app to open in a new tab
5. Click Save

The app tile appears on your board. Drag it wherever you want.

Adding Widgets

Widgets show live data from your services. Click + Add → Widget and choose from:

• Clock — current time with timezone support
• Weather — local weather via OpenWeatherMap or built-in provider
• System info — CPU, RAM, disk usage via Dash. integration
• Calendar — events from iCal feeds
• Media — now playing from Plex, Jellyfin, or Emby
• Downloads — active downloads from qBittorrent, Transmission, SABnzbd
• DNS stats — Pi-hole or AdGuard Home query stats
• Torrent monitoring — seeding, downloading, paused counts
• Docker stats — container status from your Docker socket

Integrations

This is where Homarr really shines. Integrations pull live data from your services and display it directly on your dashboard.

Configuring an Integration

1. Go to Settings → Integrations (or click the integration icon on an app tile)
2. Select the service type (e.g., Sonarr, Radarr, Jellyfin)
3. Enter the URL and API key
4. Test the connection
5. Save — the widget will now show live data

Popular Integrations

Media Management:

• Sonarr, Radarr, Lidarr, Readarr — upcoming releases, queue status, calendar
• Jellyfin, Plex, Emby — active streams, library stats
• Jellyseerr, Overseerr — pending media requests

Downloads:

• qBittorrent, Transmission, Deluge — active transfers, speeds
• SABnzbd, NZBGet — Usenet download progress
• Aria2 — general download management

Infrastructure:

• Proxmox — VM and container status
• TrueNAS — pool health, disk status
• Docker Hub, GitHub Container Registry — image update notifications
• OpenMediaVault — storage monitoring

DNS & Network:

• Pi-hole — queries blocked, top clients
• AdGuard Home — filtering stats
• OPNsense — firewall status

DevOps:

• GitHub, GitLab, Codeberg — repository activity
• Coolify — deployment status

Home Automation:

• Home Assistant — entity states, sensor data

Other:

• Nextcloud — storage, user activity
• ntfy — notification counts
• iCal — calendar events from any iCal source

User Management

Homarr has proper multi-user support — unusual for a dashboard app.

Creating Users

Go to Settings → Users to manage accounts. You can:

• Create users with different permission levels
• Organize users into groups
• Set board-level permissions (who can view/edit which boards)
• Assign integration access per user

Single Sign-On

Homarr supports OIDC and LDAP for SSO. If you’re running Authentik or Keycloak:

1. Go to Settings → Authentication
2. Configure your OIDC provider with the client ID and secret
3. Set the discovery URL (e.g., https://auth.example.com/application/o/homarr/.well-known/openid-configuration)
4. Enable auto-provisioning if you want new SSO users created automatically

For LDAP, point Homarr at your LDAP server with the base DN and bind credentials.

Board Customization

Multiple Boards

You can create separate boards for different purposes:

• Main — overview of everything
• Media — Plex, Sonarr, Radarr, downloads
• Infrastructure — Proxmox, TrueNAS, monitoring
• Family — simplified board for non-technical household members

Each board can have different access permissions.

Layout and Styling

• Grid system — drag to resize tiles to any grid size
• Sections — group related apps with collapsible sections
• Colors — customize tile colors and opacity
• Background — set a custom background image or color
• Icon picker — 11,000+ icons from Dashboard Icons, Walkx, and Papirus sets, searchable by name

The Search Bar

Press / or click the search icon to open Homarr’s global search. It searches across:

• Your apps and bookmarks
• Integration data (e.g., search for a movie in Radarr)
• Web searches (configurable search engine)

This is surprisingly useful once you have 30+ services.

Reverse Proxy Configuration

Caddy

Nginx

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

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    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;

        # WebSocket support (required for real-time updates)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

WebSocket support is important — Homarr uses WebSockets for real-time widget updates.

Docker Socket Integration

Mounting the Docker socket (/var/run/docker.sock) lets Homarr:

• Auto-discover running containers
• Show container status (running, stopped, health)
• Start/stop containers from the dashboard
• Display resource usage per container

If you’re security-conscious, use a Docker socket proxy like Tecnativa/docker-socket-proxy instead of mounting the raw socket:

services:
  dockerproxy:
    image: ghcr.io/tecnativa/docker-socket-proxy:latest
    container_name: dockerproxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1
      - IMAGES=1
      - SERVICES=1
      - TASKS=1
      - POST=0  # Read-only
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:2375:2375"

  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - ./appdata:/appdata
    environment:
      - TZ=America/New_York
      - SECRET_ENCRYPTION_KEY=your-random-32-char-secret-here
      - DOCKER_HOST=tcp://dockerproxy:2375
    depends_on:
      - dockerproxy

Backup and Restore

Homarr stores everything in the appdata directory — the SQLite database, your board configs, and uploaded assets.

Backup

# Stop Homarr first for a clean backup
docker compose stop homarr
tar czf homarr-backup-$(date +%Y%m%d).tar.gz appdata/
docker compose start homarr

Restore

docker compose stop homarr
rm -rf appdata/
tar xzf homarr-backup-YYYYMMDD.tar.gz
docker compose start homarr

For automated backups, add this to your crontab:

0 3 * * * cd ~/homarr && docker compose stop homarr && tar czf /backups/homarr-$(date +\%Y\%m\%d).tar.gz appdata/ && docker compose start homarr

Or better yet, use Kopia to back up the appdata directory on a schedule.

Updating

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

Homarr handles database migrations automatically on startup.

Troubleshooting

Dashboard loads but widgets show errors

Check that your integration URLs and API keys are correct. A common mistake: using localhost in integration URLs when Homarr runs in Docker. Use your server’s LAN IP or the container name if on the same Docker network.

WebSocket connection failed

Your reverse proxy needs to forward WebSocket connections. See the Nginx config above — the Upgrade and Connection headers are required.

Icons not loading

Homarr fetches icons from external CDNs on first use, then caches them. If you’re behind a strict firewall, icons may fail to load initially. They’ll work once cached.

High memory usage

Homarr with many integrations can use 300-500MB. If you’re on a Raspberry Pi, limit the number of active integrations and increase swap space:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Docker socket permission denied

If Homarr can’t read containers, check the socket permissions:

ls -la /var/run/docker.sock

The Homarr container runs as a non-root user. Either use the Docker socket proxy (recommended) or ensure the container user has access to the Docker group.

SECRET_ENCRYPTION_KEY errors

If you change or lose your encryption key, Homarr can’t decrypt stored integration credentials. You’ll need to re-enter all API keys. Back up this key somewhere safe.

Power User Tips

1. Keyboard shortcuts — press ? to see all available shortcuts, / for search
2. Custom CSS — inject custom styles through Settings → Customization for pixel-perfect theming
3. API access — Homarr has an API you can use to programmatically manage boards and apps
4. Multi-host monitoring — connect multiple Docker sockets (via proxy) to monitor containers across servers
5. Ping monitoring — enable ping checks on apps to show up/down status on tiles
6. Mobile bookmarks — add Homarr to your phone’s home screen as a PWA for native app-like access
7. Import/export — export your board configuration for backup or migration between instances

Wrapping Up

Homarr hits a sweet spot: it’s more powerful than a simple bookmark page, but doesn’t require you to learn YAML or edit config files. The drag-and-drop editor, 40+ integrations, built-in auth, and 11K+ icon library make it one of the most polished dashboard options for self-hosters.

If you’re the type who enjoys tweaking YAML files, Homepage might be more your speed. But if you want something your whole household can use without a terminal, Homarr is hard to beat.

Useful links:

• Homarr GitHub
• Homarr Documentation
• Homarr Discord