How to install Homarr v1 with Docker (with optional Authentik SSO)

Homarr is a modern dashboard for your homelab. Instead of a page of bookmarks, you get a drag-and-drop board of tiles that can show live information: which containers are running, what is downloading, what is playing on Jellyfin, the weather, your calendar and plenty more. Version 1 was a complete rewrite, with proper user accounts, multiple boards, permissions and single sign-on built in.

In this guide we will install Homarr v1 with Docker, give it (read-only) access to Docker so it can show your containers, and optionally hook it up to Authentik so you log in with your existing SSO account.

STEP 1: Create the folders

mkdir -p /path/to/appdata/homarr/appdata
cd /path/to/appdata/homarr

/path/to/appdata/homarr/
    docker-compose.yml
    .env                          # your secrets live here, never in the compose file
    appdata/                      # database, uploaded icons and certificates

STEP 2: Generate the encryption key

Homarr encrypts the passwords and API keys you give it for integrations (Jellyfin, Sonarr and so on). It needs a 64-character hex key to do that:

openssl rand -hex 32

Copy the output into a new .env file next to where your compose file will live, and lock the file down:

cat > .env <<'ENV'
SECRET_ENCRYPTION_KEY=CHANGE_ME_PASTE_THE_64_CHARACTER_KEY_HERE
ENV
chmod 600 .env

STEP 3: Create a Docker network

If your other homelab apps already share a network, use that. Otherwise create one:

docker network create homelab

STEP 4: The compose file

Pick the tab that suits you. If you are not sure, start with Local accounts; you can switch to SSO later without losing anything.

Option A: Local accounts

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:v1.77.2
    container_name: homarr
    restart: unless-stopped
    environment:
      - TZ=Europe/London
      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
    volumes:
      - /path/to/appdata/homarr/appdata:/appdata
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - 7575:7575
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:7575/ || exit 1"]
      interval: 1m30s
      timeout: 10s
      retries: 3
    networks:
      - homelab

networks:
  homelab:
    external: true

Option B: With Authentik SSO

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:v1.77.2
    container_name: homarr
    restart: unless-stopped
    environment:
      - TZ=Europe/London
      - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
      # Single sign-on through Authentik (OIDC)
      - AUTH_PROVIDERS=oidc,credentials
      - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
      - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - AUTH_OIDC_ISSUER=https://auth.example.com/application/o/homarr/
      - AUTH_OIDC_CLIENT_NAME=Authentik
      - AUTH_OIDC_SCOPE_OVERWRITE=openid email profile groups
      - AUTH_OIDC_GROUPS_ATTRIBUTE=groups
      - AUTH_LOGOUT_REDIRECT_URL=https://auth.example.com/application/o/homarr/end-session/
      # Skip Homarr's login page and go straight to Authentik
      - AUTH_OIDC_AUTO_LOGIN=false
    volumes:
      - /path/to/appdata/homarr/appdata:/appdata
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - 7575:7575
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:7575/ || exit 1"]
      interval: 1m30s
      timeout: 10s
      retries: 3
    networks:
      - homelab

networks:
  homelab:
    external: true

Add the client ID and secret from Authentik (see STEP 9 below) to your .env file:

SECRET_ENCRYPTION_KEY=CHANGE_ME_PASTE_THE_64_CHARACTER_KEY_HERE
OIDC_CLIENT_ID=CHANGE_ME_CLIENT_ID
OIDC_CLIENT_SECRET=CHANGE_ME_CLIENT_SECRET

STEP 5: The settings explained

STEP 6: Start Homarr

cd /path/to/appdata/homarr
docker compose up -d
docker compose logs -f

When you see that the server is listening, press Ctrl+C and open http://192.168.1.20:7575 (swap in your Docker host's IP).

STEP 7: First-run setup

1. Choose how to start. Pick Start from scratch, or Import if you have an export from an older Homarr.
2. Create the admin account. Enter a username and a strong password such as CHANGE_ME_STRONG_PASSWORD. Even if you plan to use SSO, this local account is your way back in if Authentik is ever down.
3. Basic settings. Choose whether to send anonymous usage data and whether search engines may index your dashboard (say no for a private dashboard).
4. Create your first board. Click New board, give it a name such as home, and make it the default board under Settings → Boards (or from the board's own menu).
5. Add the Docker integration. Go to Management → Integrations → New integration → Docker. It uses the socket we mounted, so there is nothing else to fill in.
6. Add apps and tiles. Open your board, click the pencil to enter edit mode and add items: App tiles for links, Docker containers, Calendar, Media server and so on. Integrations such as Jellyfin or Sonarr need the app's URL and an API key, which Homarr stores encrypted.

STEP 8: Put Homarr behind a reverse proxy

SSO only works over the same hostname that you registered as the redirect URI, so set up the proxy before testing logins.

Option A: Traefik (Docker labels)

    labels:
      - traefik.enable=true
      - traefik.http.routers.homarr.rule=Host(`home.example.com`)
      - traefik.http.routers.homarr.entrypoints=websecure
      - traefik.http.routers.homarr.tls.certresolver=cloudflare
      - traefik.http.services.homarr.loadbalancer.server.port=7575

Traefik needs to be on the homelab network for this to work. Match the entry point and resolver names to your own Traefik config.

Option B: Traefik (file provider)

http:
  routers:
    homarr:
      rule: Host(`home.example.com`)
      entryPoints:
        - websecure
      tls:
        certResolver: cloudflare
      service: homarr
  services:
    homarr:
      loadBalancer:
        servers:
          - url: http://192.168.1.20:7575

Option C: Cloudflare Tunnel

Add a public hostname of home.example.com to your tunnel pointing at http://192.168.1.20:7575. Consider putting a Cloudflare Access policy in front if Homarr shows anything you would rather keep private.

STEP 9: Single sign-on with Authentik (optional)

If you already run Authentik, logging into Homarr with the same account is a nice touch, and group membership can control who is an admin.

1. In Authentik, go to Applications → Applications → Create with provider.
2. Name it Homarr and set the slug to homarr. The slug is part of the issuer URL, so if you pick something else, change AUTH_OIDC_ISSUER to match.
3. Choose OAuth2/OpenID Connect as the provider type, with client type Confidential.
4. Add a Strict redirect URI of https://home.example.com/api/auth/callback/oidc (use your real Homarr hostname).
5. Save, then copy the Client ID and Client Secret into .env as OIDC_CLIENT_ID and OIDC_CLIENT_SECRET.
6. Create an Authentik group called homarr-admins and add yourself to it.
7. In Homarr, go to Management → Groups, create a group with exactly the same name, homarr-admins, and give it the permissions you want.
8. Recreate the container so it picks up the new settings: docker compose up -d.

Log out and you should now see a Sign in with Authentik button. Once you are happy it works, you can set AUTH_OIDC_AUTO_LOGIN=true.

Updating Homarr

1. Read the release notes for every version between yours and the new one.

Change the version in image: to the new tag (or leave it on latest), then pull and restart:

docker compose pull
docker compose up -d
docker image prune -f

Back up the data folder:

cd /path/to/appdata/homarr
docker compose stop
tar czf ~/homarr-backup-$(date +%F).tar.gz appdata .env

Homarr migrates its database automatically on start-up, so give it a minute before you panic about a blank page.

Troubleshooting

The container exits straight away complaining about the encryption key. SECRET_ENCRYPTION_KEY must be exactly 64 hex characters. Regenerate it with openssl rand -hex 32 and make sure there are no quotes or spaces in .env. Run docker compose config | grep -c SECRET_ENCRYPTION_KEY to check the variable is being picked up (that command prints a count, not the key).

The Docker tiles show nothing. Check the socket mount is present with docker inspect homarr --format '{{json .Mounts}}'. If you use a socket proxy, make sure it allows CONTAINERS=1.

Authentik says redirect_uri does not match. The redirect URI in Authentik must exactly match the hostname you are visiting, including https:// and /api/auth/callback/oidc. Browsing to Homarr by its IP address will not work with SSO.

Login works but I end up back on the login page. Usually the issuer is wrong. For Authentik it looks like https://auth.example.com/application/o/homarr/, with the trailing slash. Check the container logs for the exact error.

SSO users are not admins. Group names must match exactly in both Authentik and Homarr, and the groups scope must be included. Log out and back in after changing groups; memberships are synced at login.

And that's your dashboard sorted. Spend a happy evening arranging tiles until it is just right. 🧩