Homarr Dashboard: A Front Door for Your Docker Containers

The Problem Every Homelab Owner Recognizes

This guide covers the complete Homarr dashboard Docker Portainer setup. It starts innocently enough. You install Home Assistant. Then Jellyfin. Then Nextcloud, Portainer, Paperless-ngx, and a handful of other services you found on a Reddit thread at midnight. Before long, your browser bookmarks folder is a mess, and you are typing raw IP address strings like 10.10.10.8:8123 from memory every single day.

Sound familiar? The r/homelab and r/homarr communities are full of posts from people in exactly this situation. The moment you cross five self-hosted apps, remembering which port belongs to which service becomes a genuine time sink. You need a single, organized front door.

That front door is Homarr.

Why This Is a Privacy Decision, Not Just a Convenience Decision

Most people treat a homelab dashboard as a convenience tool. It is also a privacy decision.

When you rely on browser bookmarks synced to a cloud account, you are handing your internal network topology to a third party. Here is what you eliminate by switching to a self-hosted dashboard:

• Google Chrome sync uploading your internal service URLs to Google’s servers
• Microsoft Edge bookmark telemetry recording which local services you access
• Third-party “new tab” browser extensions that phone home with your browsing habits

What Homarr Actually Is (And What It Isn’t)

Homarr is a visual dashboard for your self-hosted services. It gives you an icon-rich grid of tiles, each linking to one of your running apps. It is not a container management tool. You cannot restart containers, read logs, or modify Docker networks from within Homarr. That is Portainer’s job.

The Reddit debate between Homepage and Homarr is real and ongoing. Homepage is a strong alternative, particularly for users who prefer configuring everything in YAML files and want maximum widget density. Homarr wins on visual UX and Docker-native auto-import. For non-technical household members who just want to click a tile and open Jellyfin, Homarr is the cleaner choice.

One-line verdict: Homarr is the front door. Portainer is the engine room. You need both.

Prerequisites and Hardware Requirements

What You Need Before You Start

• A running Docker environment, either standalone or managed via Portainer
• Portainer accessible in your browser (recommended for both routes in this guide)
• Approximately 15 minutes of uninterrupted setup time
• Basic understanding of what a Docker volume mount is (required for the Pro route only)

If you do not yet have Docker and Portainer running, start here: Build Your Privacy Machine Room: Docker + Portainer on Proxmox LXC.

Hardware Requirements

Homarr runs on any machine that supports Docker. It requires no GPU and no special CPU architecture. If your machine runs Docker, it runs Homarr.

Port and Network Notes

Homarr listens on port 7575 by default. Before deploying, verify that port is free on your host machine.

sudo ss -tulpn | grep 7575

If the command returns no output, the port is available. If something is already listening there, remap the host port in the compose file. That process is covered in the Troubleshooting section.

Method 1: Homarr Dashboard Docker Portainer — Quick Start

Who This Route Is For

This route is for you if you are currently typing IP addresses from memory, your bookmarks are a mess, and you run somewhere between five and ten self-hosted apps. The goal is a working dashboard with manually added app tiles in under 15 minutes. No Docker socket mounting. No advanced configuration. Just a running container with a usable UI.

Step 1: Deploy the Homarr Stack in Portainer

1. Open Portainer in your browser.
2. Navigate to Stacks in the left sidebar.
3. Click Add Stack.
4. Give your stack a name, for example homarr.
5. Paste the following compose definition into the Web Editor:

services:
  homarr:
    image: ghcr.io/ajnart/homarr:latest
    container_name: homarr
    ports:
      - "7575:7575"
    volumes:
      - ./homarr/configs:/app/data/configs
    restart: unless-stopped

6. Click Deploy the stack at the bottom of the page.

Portainer will pull the image and start the container. This typically takes under 60 seconds on a decent connection.

Step 2: Access the Dashboard for the First Time

Open your browser and navigate to http://[YOUR-SERVER-IP]:7575. Replace [YOUR-SERVER-IP] with the actual LAN IP of your Docker host.

You will land on an empty canvas. Homarr presents a grid with a prompt to add your first app. The interface is drag-and-drop and every option is labeled.

Step 3: Add Your First App Tile Manually

1. Click Add App (or the plus icon on the canvas).
2. Fill in the following fields:
   • Name: The display name, for example Home Assistant
   • URL: The full address, for example http://10.10.10.8:8123
   • Icon: Type the app name and let Homarr’s built-in icon search fetch the official logo automatically
3. Click Save.
4. Repeat for each service you want on the dashboard.

Step 4: Set Homarr as Your Browser Homepage

• Chrome: Settings → On startup → Open a specific page → enter http://[SERVER-IP]:7575
• Firefox: Settings → Home → Custom URLs → enter the same address
• Safari: Preferences → General → Homepage → enter the address

Method 2: The Pro Setup (Docker Socket Integration)

Who This Route Is For

This route is for you if you run 20 or more containers, want live status indicators on every tile, and have no interest in manually entering app details one by one. Homarr reads directly from the Docker engine. Your containers appear automatically, with names and ports pre-filled. You handle the visual arrangement; Homarr handles the data.

The Docker Socket: What It Is and Why It Matters

The file at /var/run/docker.sock is a Unix socket that allows processes to communicate directly with the Docker daemon. When you mount it into a container, that container can query Docker for information: which containers are running, what ports they expose, their current state, and more.

This is how Homarr performs its auto-import. It queries Docker directly rather than relying on you to type everything in manually.

Step 1: Deploy the Full Pro Stack in Portainer

1. Open Portainer and navigate to Stacks → Add Stack.
2. Name the stack homarr.
3. Paste the following compose definition:

services:
  homarr:
    image: ghcr.io/ajnart/homarr:latest
    container_name: homarr
    ports:
      - "7575:7575"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./homarr/configs:/app/data/configs
      - ./homarr/icons:/app/public/icons
      - ./homarr/data:/data
    restart: unless-stopped

4. Click Deploy the stack.

Step 2: Configure the Docker Integration Inside Homarr

1. Open Homarr at http://[SERVER-IP]:7575.
2. Navigate to Settings → Integrations.
3. Click Add Integration and select Docker.
4. In the socket path field, enter: /var/run/docker.sock
5. Save the integration and return to the main dashboard.

Step 3: Smart Import from Running Containers

1. Click Add App on the dashboard canvas.
2. Instead of a blank form, you will see a list of your running containers, populated automatically by the Docker integration.
3. Select the containers you want to add as tiles.
4. Homarr generates tiles with the correct names and URLs pre-filled.

Step 4: Icons and Visual Polish

For each tile, click the icon field and type the application name as it is commonly known. For example: Nextcloud, Jellyfin, Portainer, Paperless. Homarr’s built-in search queries the dashboard-icons repository and returns official SVG logos.

Use the exact product name for the best match. Abbreviations and typos will return no results or the wrong icon. Once icons are set, your dashboard will display live ping indicators (green dots for reachable services) and container state badges showing Running or Stopped without opening Portainer.

Configuration and Validation: How to Test Everything Works

The Three-Point Validation Checklist

• Tile click test: Does clicking a tile open the correct app in a new tab?
• Ping status test: Is there a green dot next to each active service?
• Docker status test: Does Homarr show container state (Running or Stopped) without opening Portainer?

All three should pass before you consider the setup complete.

Validating the Docker Socket Connection

To confirm at the CLI level that the socket is correctly mounted inside the running container, run the following on your Docker host:

docker inspect homarr | grep -A5 "Mounts"

Look for an entry showing /var/run/docker.sock in the source field. If it is present, the socket is mounted correctly. If the Homarr UI still shows no containers, proceed to the Troubleshooting section.

Setting Homarr as Your Browser’s Default Homepage

If you completed Method 1 and skipped ahead, revisit Step 4 of that section. The URL to set is http://[SERVER-IP]:7575. Every new browser tab now opens your self-hosted navigation hub.

The Ugly Truth: Homarr’s Limitations

What Homarr Cannot Do

We believe in honest documentation. Here is what Homarr will not do, regardless of how you configure it:

• Cannot restart or stop containers (use Portainer or the CLI for that)
• Cannot view container logs
• Cannot manage Docker networks or volumes
• Cannot replace Portainer, Dockge, or Yacht as a management interface

Homarr is a dashboard. It observes and links. It does not control.

The “Homepage vs. Homarr” Debate: Our Honest Take

The r/homelab community is genuinely split on this, and both camps have valid arguments. Homepage is a powerful alternative. It uses a YAML-first configuration model, offers a wider variety of widgets, and is better suited to users who are comfortable living in config files and want maximum information density.

Homarr wins on visual UX. The drag-and-drop interface, the icon search, and the Docker auto-import workflow are faster and more accessible for non-technical users in your household. If your partner or family members also use the homelab, Homarr is the more approachable choice.

When You Should Consider Switching to Homepage Instead

• You prefer managing all configuration in version-controlled YAML files
• You are running a Kubernetes environment where Docker socket integration is not applicable
• You need a high density of information widgets on a single screen
• You have no non-technical users who need to interact with the dashboard

Troubleshooting Common Errors

Problem: Container List Stays Empty After Docker Integration

Symptom: The Integrations panel shows Docker as connected, but no containers appear when you click Add App.

Root causes:

• The socket volume was not included in the stack definition
• The wrong socket path was entered in Homarr’s integration settings

Fix:

1. In Portainer, navigate to your Homarr stack and click Editor.
2. Verify the volumes section includes the following line:

      - /var/run/docker.sock:/var/run/docker.sock

3. If it is missing, add it, then click Update the stack.
4. After the container restarts, return to Homarr Settings → Integrations and confirm the socket path is set to /var/run/docker.sock exactly.

Problem: Broken Images / Icons Not Loading

Symptom: Tiles display a broken image icon instead of the app logo.

Root cause: Homarr fetches icons from an external CDN at runtime. If the container cannot resolve external hostnames, the fetch fails silently.

Fix options:

1. Verify your container has outbound DNS access:

docker exec homarr nslookup cdn.jsdelivr.net

2. If DNS resolution fails, check your Docker network configuration and ensure the container has a working DNS resolver.
3. As a manual fallback, use the Icon Picker inside Homarr to upload a local SVG file for each tile.

Problem: Dashboard Loads But Tiles Return “Connection Refused”

Symptom: Homarr loads correctly and tiles are visible, but clicking a tile opens a browser error page.

Root cause: The URL stored in the tile uses localhost instead of the server’s LAN IP address. From your browser’s perspective, localhost refers to your own computer, not the server.

Fix: Edit the affected tile and replace localhost with the actual LAN IP of your Docker host. For example, change http://localhost:8096 to http://10.10.10.8:8096.

Problem: Port 7575 Already in Use

First, identify what is using the port:

sudo ss -tulpn | grep 7575

If a conflict exists, change the host-side port mapping in your compose file. The container port stays the same; only the left side of the mapping changes:

    ports:
      - "7576:7575"

Redeploy the stack and access Homarr at http://[SERVER-IP]:7576 instead.

Conclusion and Next Steps

Your Completion Checklist

• Homarr stack deployed in Portainer
• Docker socket successfully mounted for live container data
• All containers imported and equipped with icons
• Dashboard set as the default browser homepage
• Three-point validation passed (tile clicks, ping status, Docker state)

What You Have Actually Built

This is not just a dashboard. It is a private navigation hub with zero external dependency. No Google account sees your internal service map. No Microsoft telemetry records which apps you access. No third-party extension has visibility into your network topology.

Every tile on that screen is a service you own, running on hardware you control, accessible only to people you authorize.

The Next Mission: HomeWizard P1 Meter into Home Assistant into Homarr

Now that your dashboard is live, the next step is to make it smarter. The upcoming guide walks you through integrating the HomeWizard P1 energy meter with Home Assistant. The result is a live energy consumption widget on this exact Homarr dashboard, showing real-time power usage without opening a single other app.

Your front door is built. Now let’s put something worth watching on it.

Further Reading and Community Resources

• Official Homarr Documentation
• r/homarr on Reddit
• SelfHostHero: Build Your Privacy Machine Room with Docker and Portainer
• SelfHostHero: Paperless-ngx on Portainer — a great first tile for your new dashboard
• SelfHostHero: Install Jellyfin on Proxmox — another essential dashboard tile