Homarr Guide: Your Ultimate Dashboard for Self-Hosted Services

Homarr Guide: Your Ultimate Dashboard for Self-Hosted Services

by

What Is Homarr? Understanding the Modern Self-Hosted Dashboard

Homarr is an open-source, lightweight dashboard application designed specifically for managing and accessing self-hosted services. Unlike generic start pages or bookmark managers, Homarr provides a unified, visually cohesive interface that integrates directly with your existing Docker containers, applications, and network services. It operates as a static web application built with Next.js, requiring minimal system resources while delivering real-time status updates, service monitoring, and customizable layouts. The project is actively maintained on GitHub under the MIT license, ensuring transparency and community-driven development. Homarr distinguishes itself through deep integration with popular self-hosted tools like Sonarr, Radarr, Plex, and Grafana, automatically pulling status data and metadata without manual configuration.

Core Features That Set Homarr Apart

Real-Time Service Monitoring

Homarr excels at live status tracking. Each service tile displays current operational state—online, offline, or partially degraded—using color-coded indicators. The dashboard polls your services at configurable intervals, updating without requiring page refreshes. This is achieved through WebSocket connections and REST API integrations, meaning a failed download client or offline media server is instantly visible. Unlike static dashboards, Homarr can show recent activity (e.g., “3 downloads completed in the last hour”) directly on the tile.

Docker Integration and Automatic Discovery

For environments running Docker, Homarr can auto-discover running containers via the Docker socket. It reads container labels and exposed ports, generating service tiles without manual entry. This feature supports Docker Compose stacks, allowing you to organize services by project name. The integration extends to Docker health checks—containers marked as “unhealthy” in Docker automatically reflect that status on the dashboard. This eliminates the maintenance burden of manually updating service endpoints when containers restart or change ports.

Integrated Search with Search Providers

Homarr includes a built-in universal search bar that can query multiple search engines simultaneously. By default, it supports Google, DuckDuckGo, Bing, and custom self-hosted search engines like SearXNG. You can set default search providers per user profile and even define custom shortcuts (e.g., typing “!r query” searches Radarr). The search bar supports autocomplete from your browser’s history or custom bookmarks, making it a functional replacement for browser new-tab pages.

Customizable Layouts with Drag-and-Drop

The dashboard layout is fully grid-based and responsive. You can resize, reorder, and group tiles into categories (e.g., “Media,” “Monitoring,” “Development”). Categories can be collapsed or expanded, and each category supports custom icons and background colors. Homarr uses a 12-column grid system, allowing precise control over tile widths—from 1/12 of the screen to full width. Layouts are saved per user, enabling different configurations for administrators versus regular users.

User Authentication and Multi-User Support

Homarr supports user accounts with role-based access control. Three roles exist: Admin, User, and Read-Only. Admins can manage all settings, categories, and service configurations. Users can customize their own layout but cannot modify global settings. Read-Only users see the dashboard with no editing capabilities. Authentication can be local (with password hashing) or integrated with OAuth providers like Authelia, Authentik, or LDAP. This makes Homarr suitable for shared self-hosted environments where different family members or team members need tailored views.

Backup, Restore, and Export

Configuration, user data, and layout preferences are stored in a SQLite database (with PostgreSQL support coming). You can export the entire configuration as a JSON file, allowing easy migration between servers or version control backup. The backup includes all service definitions, custom categories, and user settings. Homarr also supports automated nightly backups to local directories or network shares.

Step-by-Step Installation Guide

Prerequisites

  • A Linux server (Ubuntu 22.04 LTS recommended) or any system with Docker support
  • Docker Engine 20.10+ and Docker Compose v2+
  • Minimum 512MB RAM and 1GB disk space
  • A domain or subdomain (if exposing externally via reverse proxy)
  • Port 7575 (default) or 3000 (development) available

Method 1: Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'
services:
  homarr:
    image: ghcr.io/ajnart/homarr:latest
    container_name: homarr
    restart: unless-stopped
    ports:
      - '7575:7575'
    volumes:
      - ./homarr/configs:/app/data/configs
      - ./homarr/icons:/app/public/icons
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - TZ=America/New_York
      - HOMARR_SERVER_HOST=0.0.0.0
      - HOMARR_SERVER_PORT=7575

Run docker-compose up -d. Access Homarr at http://your-server-ip:7575. The Docker socket mount enables auto-discovery; omit if not using Docker integration.

Method 2: Bare Metal with Node.js

For servers without Docker, install Node.js 18+:

git clone https://github.com/ajnart/homarr.git
cd homarr
cp .env.example .env
# Edit .env with your settings
npm install
npm run build
npm run start

This runs Homarr directly; use PM2 or systemd for persistence.

Method 3: Using Docker Run (Quick Start)

For testing or single-command deployment:

docker run -d 
  --name homarr 
  -p 7575:7575 
  -v ./homarr/configs:/app/data/configs 
  -v /var/run/docker.sock:/var/run/docker.sock 
  ghcr.io/ajnart/homarr:latest

Configuration and Initial Setup

First Login and Admin Account

Navigate to your Homarr URL. The first time you access the dashboard, you will be prompted to create an admin account. Provide a username, email, and strong password. This account is stored locally and cannot be reset via the UI—back up your configs volume.

Adding Services Manually

Click the “Manage” button in the top bar, then “Services.” Choose “Add Service” and fill in:

  • Name: Display label (e.g., “Plex”)
  • URL: Full URL including port (e.g., http://192.168.1.50:32400/web)
  • Icon: Search from Homarr’s built-in icon library (over 1,000 icons from Font Awesome, Simple Icons, and custom SVGs)
  • Status Check URL: API endpoint for health (optional but recommended). For example, Plex’s /status/sessions endpoint.
  • Category: Assign to an existing or new category.

Configuring Docker Auto-Discovery

Ensure the Docker socket is mounted. In the Settings panel, navigate to “Docker” and toggle “Enable Docker Integration.” Homarr will scan all running containers. Containers with exposed ports and labels (e.g., homarr.service=true) are automatically added. You can manually exclude containers by setting homarr.enabled=false in their labels.

Setting Up Status Monitoring

For each service, you can define a health check interval (15 seconds to 1 hour). Homarr sends HTTP GET requests to the status check URL. It expects a 200 response code for “online.” For more advanced checks, you can define a JSONPath query (e.g., expecting {"status":"ok"}). If the service returns a non-200 or times out, the tile turns red.

Integrating with Widgets and Services

Homarr includes widgets beyond simple links. Go to “Widgets” in the manage menu to add:

  • Clock: Analog or digital, timezone-aware.
  • Weather: Uses OpenWeatherMap API; requires API key.
  • RSS Feed: Display latest posts from any RSS source.
  • Calendar: Integrates with CalDAV (e.g., Nextcloud, iCloud).
  • Uptime Monitor: Lists services with uptime percentages.
  • Search: The universal search bar as a widget.
  • Docker Stats: Real-time CPU/memory usage of containers.

Advanced Customization and Optimization

Theming and CSS Overrides

Homarr supports both light and dark themes, plus user-defined accent colors. Navigate to “Settings” > “Appearance.” You can upload a custom logo, set a background image (with blur overlay), and define primary/secondary colors. For advanced users, Homarr allows injecting custom CSS in the settings panel. For example, to change tile border radius:

.service-tile {
  border-radius: 20px !important;
  box-shadow: 0 8px 32px rgba(0,0,0,0.2);
}

Environment Variables for Headless Configuration

For automated deployments, you can pre-configure Homarr using environment variables:

  • HOMARR_SERVER_HOST – Bind address (default 0.0.0.0)
  • HOMARR_SERVER_PORT – Port (default 7575)
  • HOMARR_DATABASE – Database path (default /app/data/configs/database.sqlite)
  • HOMARR_DISABLE_REGISTRATION – Set to true to prevent new user signups
  • HOMARR_DEFAULT_LOCALE – Language code (e.g., en, de, fr)

Reverse Proxy Configuration

Expose Homarr securely behind Nginx Proxy Manager, Traefik, or Caddy. Example Nginx config:

server {
  listen 443 ssl;
  server_name homarr.yourdomain.com;
  location / {
    proxy_pass http://192.168.1.100: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;
  }
}

Enable WebSocket support for real-time updates. For Traefik, add label traefik.enable=true to your Homarr container.

Performance Tuning

Homarr is lightweight by design, but you can optimize load times:

  • Reduce status polling intervals (under Settings > Monitoring).
  • Limit the number of widgets—each RSS feed or weather widget adds an API call.
  • Use a CDN for static assets if serving to multiple users over the internet.
  • Enable MongoDB or PostgreSQL (via config) for larger deployments; SQLite suffices for under 50 users.

Integrating Popular Self-Hosted Services

Media Servers (Plex, Jellyfin, Emby)

Add these as services with their respective URLs. For real-time activity, use their API endpoints:

  • Plex: /status/sessions (shows currently playing content on the tile)
  • Jellyfin: /System/Info – requires API key in header
  • Sonarr/Radarr: /api/v3/queue?apikey=YOUR_KEY (displays upcoming downloads)

Monitoring Tools (Grafana, Prometheus, Uptime Kuma)

Grafana can be embedded as an iframe widget (enable “Allow embedding” in Grafana settings). Uptime Kuma has a dedicated Homarr widget; provide its API URL to show uptime status directly on your dashboard.

Authentication Systems (Authelia, Authentik)

Homarr integrates with OpenID Connect (OIDC) for single sign-on. In Settings > Authentication, choose “OpenID Connect” and enter your provider’s endpoints. Users log in through Authelia/Authentik, and groups are mapped to Homarr roles.

File Management (Nextcloud, FileBrowser)

Add Nextcloud as a service; use the built-in “Files” widget to display recent file uploads or shared links. FileBrowser can be embedded as an iframe with a custom tile icon.

Security Best Practices

Disabling Public Registration

Prevent unauthorized access by setting HOMARR_DISABLE_REGISTRATION=true in environment variables. Only admin-created users can log in. Additionally, enforce HTTPS via reverse proxy and consider IP whitelisting for the dashboard’s admin panel.

API Key Management

Services requiring API keys (Sonarr, Radarr, Prowlarr) store them in Homarr’s database. The keys are encrypted at rest using AES-256. Never expose your Homarr instance directly to the internet without a firewall; use a VPN (WireGuard, Tailscale) for administrative access.

Session Security

Homarr uses HTTP-only cookies with SameSite=Strict for session tokens. Sessions expire after 24 hours by default (configurable). Enable CSRF protection in advanced settings for public-facing instances.

Regular Backups

Automate backups of the configs directory. Run a cron job:

0 3 * * * tar -czf /backups/homarr-$(date +%Y%m%d).tar.gz /path/to/homarr/configs

Test restoration periodically by extracting to a temporary directory and verifying the database file.

Troubleshooting Common Issues

Docker Socket Permission Denied

If Homarr cannot detect Docker containers, the Docker socket must have correct permissions. On the host, run sudo chmod 666 /var/run/docker.sock (temporary) or add the container user to the docker group. For security, mount the socket read-only (:ro).

Service Shows “Offline” Despite Being Reachable

Check if the service uses HTTPS while Homarr is on HTTP (mixed content blocking). Ensure the status check URL returns a 200 code; some services return 302 redirects. Use the “Advanced Health Check” option to match specific response body strings.

Database Lock Errors

SQLite can lock under heavy concurrent writes. If you see “database is locked” errors, switch to PostgreSQL. Set the HOMARR_DATABASE_CONNECTION environment variable to your PostgreSQL connection string.

Widgets Not Loading (CORS Issues)

Some APIs block cross-origin requests. For weather widgets, generate an API key that allows your Homarr domain. For RSS feeds, use a proxy service (or run a local RSS proxy) to bypass CORS.

Slow Page Load

Large icon packs or high-resolution background images cause delays. Compress background images to WebP format (under 500KB). Disable unused widgets in the manage panel.

Community and Support Resources

The Homarr project maintains an active Discord server with over 5,000 members, a GitHub Discussion board for feature requests, and a documentation wiki at homarr.dev/docs. Community-contributed themes, icon packs, and service templates are available on the Homarr GitHub repository under the examples directory. For bug reports, open an issue with your docker-compose.yml and browser console logs. The project releases stable updates every two months, with patch releases for critical security fixes.

Leave a Comment