How to Self-Host Homarr on Proxmox LXC — Complete Homelab Dashboard Guide 2026

If you're running more than five or six self-hosted services on Proxmox, you've probably felt the friction: different ports, different IPs, different URLs, and a growing list of browser bookmarks you have to maintain manually. The answer isn't a better bookmarks manager — it's a proper homelab dashboard. Homarr is one of the best options in the self-hosted space right now: a clean, modern dashboard built with Next.js that puts all your services behind a single, well-organized page.

In this guide, I'll walk you through the complete process of deploying Homarr on Proxmox using an LXC container. We'll create a lightweight Ubuntu container, enable the right nesting settings for Docker to work, deploy Homarr via Docker Compose, configure service tiles and widgets, and optionally expose the dashboard over HTTPS using Traefik. The whole setup takes about 20–30 minutes, and once it's done your homelab immediately becomes easier to navigate.

What Is Homarr and Why Use It?

Homarr is an open-source homelab dashboard that acts as a personal portal to all your self-hosted applications. You add tiles for each service — Jellyfin, Vaultwarden, Paperless-ngx, Navidrome, whatever you're running — and each tile shows the app name, icon, URL, and live status. The dashboard is fully customizable: you can resize and drag tiles, group them into sections, and switch between light and dark themes. It's the kind of tool that makes a homelab feel finished rather than like a collection of scattered services.

Beyond simple bookmarks, Homarr has genuine service integrations. It can connect to the Docker socket and auto-detect running containers. It also supports integrations for apps like Radarr, Sonarr, Jellyfin, Overseerr, and qBittorrent — pulling in queue status, media counts, and download progress directly onto dashboard widgets. There are also calendar, weather, RSS reader, and clock widgets you can add alongside your app tiles.

According to the official Homarr documentation, the project is actively maintained and supports Docker (the recommended install method), as well as bare-metal npm deployments and community-maintained packages for Unraid and TrueNAS. For a Proxmox homelab where you're managing services as LXC containers, Docker inside a dedicated LXC is the cleanest approach: one LXC for the dashboard, isolated from everything else, easy to snapshot and restore if something goes wrong during an update.

I run Proxmox VE on a Beelink GTi13 Ultra (i9-13900HK, 64GB RAM) and a Dell OptiPlex 7090, with most workloads split across LXC containers on both nodes. If you're new to this approach, the Proxmox LXC Complete Self-Hosting Guide covers the fundamentals before you follow along here. For anyone still shopping for a node, the Beelink SER5 Mini PC (~$299) is a well-regarded entry point — the Ryzen 5 5500U with 16GB RAM is more than enough to run a full homelab stack of 8–10 LXC containers, per Beelink's published spec sheet.

Prerequisites Before You Begin

This guide assumes you have a working Proxmox VE node (version 8.x recommended) and access to the Proxmox web UI. Before you start, make sure the following are in place:

• An Ubuntu 22.04 or 24.04 LXC template already downloaded in Proxmox (or grab it now via Datacenter → your storage pool → CT Templates → Templates)
• At least 1GB of RAM available to dedicate to the Homarr container
• At least 10GB of storage for the container's root disk (20GB is more comfortable if you'll be caching icons and storing Homarr's SQLite database long-term)
• A static IP or DHCP reservation for the container so its address doesn't change between reboots
• Optional: Traefik already running on your network if you want HTTPS access with a proper domain

If you want a proper domain and TLS certificate for Homarr, read the Traefik v3 on Proxmox LXC guide first. You can add reverse proxy access later without redoing any of the Docker steps below — it's entirely optional for the initial deployment.

On the hardware side, keep your network in mind: once you have several services running across multiple LXC containers, good switch infrastructure matters. The TP-Link 2.5G 8-Port Switch (~$49) is a budget-friendly upgrade from 1GbE that homelab enthusiasts widely recommend for improving NAS and inter-node transfer speeds.

Step 1: Create the LXC Container in Proxmox

Open the Proxmox web UI and click Create CT in the top right corner. Work through the creation wizard with these settings:

• General: Assign a CT ID and a hostname (e.g., homarr). Set a root password you can remember.
• Template: Choose your Ubuntu 22.04 or 24.04 standard template.
• Disks: Set the root disk to at least 10GB on your fastest storage pool. Homarr's database and icon cache will grow slowly over time.
• CPU: 1–2 cores is more than enough. Homarr is not CPU-intensive at idle or under normal dashboard use.
• Memory: 1024MB. The Node.js process is lightweight; 512MB works in a pinch but 1GB gives breathing room.
• Network: Bridge to vmbr0, use DHCP, or assign a static IP directly in the wizard.

After creating the container but before starting it, there is one required configuration change. In the Proxmox UI, navigate to the container → Options → Features, and enable the Nesting feature. This is what allows Docker to run inside an unprivileged LXC container. Per the Proxmox documentation, enabling nesting grants the container the capability to create nested kernel namespaces, which Docker's container runtime requires for managing its own container lifecycle. Without it, the Docker daemon will fail to start with a capabilities error.

You do not need to make the container privileged. Unprivileged with nesting enabled is the correct, more secure configuration that the Proxmox docs recommend for running Docker in LXC. Once you've enabled nesting, start the container and open a console shell via the Proxmox UI, or SSH directly to the container's IP.

Step 2: Install Docker Inside the LXC

Once you're inside the container shell, update the system packages and install Docker using the official convenience script that Docker publishes at get.docker.com:

apt update && apt upgrade -y
apt install -y curl ca-certificates

# Docker's official install script (installs Engine + Compose plugin)
curl -fsSL https://get.docker.com | sh

# Enable Docker to start on boot and start it now
systemctl enable --now docker

# Verify both are working
docker --version
docker compose version

The get.docker.com script installs Docker Engine along with Docker Compose v2 as a CLI plugin. You should see output like Docker version 27.x.x and Docker Compose version v2.x.x from those last two commands. If the Docker daemon fails to start, go back and confirm that Nesting is enabled in the LXC's Options → Features section in Proxmox — that is almost always the cause when Docker refuses to start inside an LXC on Proxmox.

Step 3: Deploy Homarr with Docker Compose

Create a working directory for Homarr's compose file and persistent data volumes:

mkdir -p /opt/homarr
cd /opt/homarr

Homarr's current version requires a SECRET_ENCRYPTION_KEY to encrypt credentials you store for service integrations. Generate a strong one with OpenSSL:

openssl rand -hex 32

Copy that 64-character hex string — you'll paste it into the compose file below. Now create /opt/homarr/docker-compose.yml with the following contents. Replace YOUR_KEY_HERE with the key you just generated, and set TZ to your actual timezone:

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    container_name: homarr
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./appdata/configs:/app/data/configs
      - ./appdata/icons:/app/public/user-customizations/icons
      - ./appdata/data:/data
    environment:
      - TZ=America/New_York
      - SECRET_ENCRYPTION_KEY=YOUR_KEY_HERE
    ports:
      - "7575:7575"

The Docker socket mount (/var/run/docker.sock) is optional but enables Homarr to list containers running on this same Docker host. In a typical Proxmox setup where each service lives in its own LXC, the socket only sees containers on this particular LXC — you'll still add your other services as manual tiles. The socket is most useful if you co-locate multiple Docker services on the same LXC or if you specifically want Homarr to manage and display local containers. If you mount the Docker socket, be aware that any process with access to it has broad control over the Docker daemon — the Homarr docs acknowledge this tradeoff and recommend using a socket proxy like Tecnativa's docker-socket-proxy for multi-host setups.

Start Homarr and watch the initialization logs:

docker compose up -d
docker compose logs -f

Homarr initializes its SQLite database on first run, which takes 15–30 seconds. Once you see it report that it's listening on port 7575, open http://<your-lxc-ip>:7575 in a browser. You should see the Homarr first-run setup screen.

Step 4: Create Your Admin Account and Add Service Tiles

The first-run wizard prompts you to create an admin username and password. After that, you're dropped into the dashboard in edit mode — a blank canvas with a grid layout ready to fill. Here's the basic workflow for adding your first app tile:

1. Make sure Edit mode is active (click the pencil icon in the top bar)
2. Click + Add element → App
3. Enter the app name (e.g., "Jellyfin"), its internal URL (e.g., http://192.168.1.50:8096), and search for its icon
4. Optionally set a Ping URL — Homarr will check it periodically and show a live status indicator on the tile
5. Click Save

Homarr ships with a built-in icon library covering hundreds of self-hosted applications. Just type the app name in the icon search and it will suggest matching icons. Jellyfin, Vaultwarden, Paperless-ngx, Nextcloud, Navidrome, Uptime Kuma, Home Assistant, Portainer, Traefik — they're all there. If an icon isn't in the library, you can upload a custom PNG or SVG and it will be stored in the ./appdata/icons directory.

For live health checks, the Ping URL is separate from the navigation URL. Set it to the app's health endpoint or root URL. This gives you Uptime Kuma-style status at a glance right on the dashboard — useful for spotting a downed service without switching to a separate monitoring page. For detailed uptime history, alerting, and incident tracking, a dedicated Uptime Kuma instance is still the right choice.

Step 5: Widgets and Service Integrations

App tiles are just the beginning. Homarr supports a set of dashboard widgets you can add alongside your service shortcuts to turn the dashboard into a genuinely useful homelab command center. You add them the same way as tiles: Edit mode → Add element → select the widget type.

• Weather: Uses the Open-Meteo API — no API key needed. Set your city or GPS coordinates and it shows current conditions and a forecast.
• Calendar: Connects to CalDAV providers including Nextcloud Calendar, Radicale, or Baikal. Shows upcoming events directly on the dashboard.
• RSS reader: Pull in headlines from any RSS feed — useful alongside a self-hosted FreshRSS or Miniflux instance.
• Date and time: A clean clock widget with configurable timezone and display formats.
• Media server integrations (Jellyfin/Emby): Shows media library counts and what's currently playing.
• Download clients (qBittorrent, Deluge, SABnzbd): Displays active downloads, speeds, and queue size.
• Media request managers (Overseerr/Jellyseerr): Shows pending request counts directly on the dashboard.
• Indexer status (Prowlarr): Reports indexer health if you run Prowlarr as part of a *arr stack.

Each widget is configured independently — you enter the URL and credentials for the service it connects to, and Homarr stores those credentials encrypted using your SECRET_ENCRYPTION_KEY. All widgets are draggable and resizable on the grid. If you have multiple household members using the homelab, each user gets their own dashboard layout — widgets and tile arrangements are per-user, not shared.

Step 6: Expose Homarr Over HTTPS with Traefik

Running Homarr at a plain http://IP:7575 is fine for local access, but a hostname and TLS certificate make the dashboard feel like a proper internal tool rather than a dev port. If you have Traefik already running on your Proxmox node (see the full Traefik v3 setup guide), add a dynamic configuration file to your Traefik config directory:

# /etc/traefik/dynamic/homarr.yml
http:
  routers:
    homarr:
      rule: "Host(`homarr.yourdomain.com`)"
      entryPoints:
        - websecure
      service: homarr
      tls:
        certResolver: letsencrypt
  services:
    homarr:
      loadBalancer:
        servers:
          - url: "http://192.168.1.120:7575"

Replace 192.168.1.120 with your Homarr LXC's actual IP and homarr.yourdomain.com with your hostname. Traefik hot-reloads dynamic config files without a restart, so the router activates immediately and a Let's Encrypt certificate is requested automatically.

For external access, pair Traefik with Headscale — a self-hosted Tailscale coordination server. This keeps Homarr accessible from your phone or laptop while traveling, without exposing it to the public internet. The combination of Traefik for HTTPS termination and Headscale for network-layer access control is a solid security posture for a homelab dashboard.

Hardware Recommendations for Your Proxmox Node

Homarr itself is lightweight — 256–512MB of RAM at idle and negligible CPU. The real capacity question is what else you're running on the same Proxmox node. A typical self-hosting stack with Jellyfin, Vaultwarden, Nextcloud, Traefik, Uptime Kuma, and Homarr alongside a few other services will want at least 16GB of RAM on the node to stay comfortable, with room for container growth.

For a first homelab machine, the Beelink SER5 Mini PC (~$299) — Ryzen 5 5500U, 16GB RAM — is a well-regarded entry point. Per Beelink's published specs, the 5500U runs at a 15W base TDP, making it reasonable to run 24/7 without worrying about electricity costs. If you want more headroom for RAM-heavy workloads like local AI inference with Ollama alongside your standard self-hosted stack, the MINISFORUM UM890 Pro (~$429) steps up to a Ryzen 9 8945HS with 32GB RAM and meaningfully more CPU performance, per MINISFORUM's published specifications.

On the network side, 1GbE is sufficient for most homelab traffic, but 2.5GbE between nodes makes NAS transfers and Proxmox live migration noticeably faster. The TP-Link 2.5G 8-Port Switch (~$49) is the most widely recommended budget option for upgrading without spending hundreds on a managed enterprise switch.

Keeping Homarr Updated

Homarr releases updates regularly. The update process with Docker Compose is the standard pull-and-recreate workflow:

cd /opt/homarr
docker compose pull          # pull the latest image from ghcr.io
docker compose up -d         # recreate the container with the new image
docker image prune -f        # clean up old image layers

Before any major update, check the Homarr releases page on GitHub for migration notes. The jump from Homarr v0.x to v1.0 required a manual database migration and a change in the Docker image registry from ghcr.io/ajnart/homarr to ghcr.io/homarr-labs/homarr, which the official migration guide documented step by step. Future major versions may include similar changes.

Taking a Proxmox snapshot of the LXC before any major update is always worth the 30 seconds it takes. Per the Proxmox documentation, LXC snapshots capture the full filesystem state of the container without requiring it to be stopped. If an update breaks something, you roll back with a single click.

Troubleshooting Common Issues

Docker fails to start inside the LXC with a capabilities error: Almost always means Nesting is not enabled. Navigate to the Proxmox UI → your Homarr container → Options → Features → enable Nesting → stop and restart the container. The feature takes effect on next boot.

Homarr container exits immediately after first start: Run docker compose logs to see the error. The most common cause is a missing or malformed SECRET_ENCRYPTION_KEY. The key must be exactly 64 hex characters — the output of openssl rand -hex 32. Check for accidental spaces or newlines if you copy-pasted it. Once the key is correct in the compose file, run docker compose up -d again.

Tiles can't reach services (status shows as offline): The service URL must be reachable from inside the Homarr container's network namespace, not just from your laptop. Test it from the LXC shell with curl -s http://<service-ip>:<port>. If that returns nothing but your laptop reaches the service fine, the issue is almost always firewall rules or VLAN segmentation blocking inter-container traffic on your network.

Icons show as a generic placeholder: Homarr fetches some icon assets from its bundled library and from external CDNs. Make sure the Homarr LXC has outbound internet access — check with curl -I https://homarr.dev from the container. If internet is blocked at the firewall level, you can upload custom icon files manually by dropping PNG or SVG files into ./appdata/icons and then selecting them in the tile editor.