Homarr

A home for your apps, bookmarks, and integrations.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Homarr

Editable Compose files in your own directory.

Start the app and use Automatic app setup to choose an administrator, create a private board and issue a scoped connection key.
Review proposed service links before adding them to the board.

selfhost app --directory ./homarr init homarr

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./homarr start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd homarr
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Homarr, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "homarr",
  "name": "Homarr",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Before configuring integrations

Later Sync plans use the saved key and private board. No global Selfhost dashboard is required.
OIDC keeps local credentials available; group membership is managed locally until you choose another policy.
Database placement includes PostgreSQL, MySQL and MariaDB using app-specific connection settings. Select a fresh or already migrated database before first start; changing the engine does not convert existing data.
Do not rotate SECRET_ENCRYPTION_KEY without Homarr recovery procedures.
Existing deployments retain their frozen recipe; new onboarding capabilities do not silently replace that definition.
MySQL and MariaDB source bindings currently require TLS mode disable and a private network. Sources requiring TLS are rejected by these bindings; certificate-aware custom deployments remain manual. PostgreSQL retains its native TLS modes.

Homarr integrations

Compose service: homarr. These operations use the profile saved when this deployment is created.

Initialize and connect

Supported setup modes: bootstrap, connect, sync.

Creates a private dashboard with only the service links you review. App credentials stay on this computer.
An interrupted remote write requires inspection before another attempt.

Setup fields

Administrator username username: string · requiredDefault: "admin"Length: 3 to 255 characters
Administrator password (8 or more characters) password: secret · requiredLength: 8 to 255 characters
Private board name (letters, digits, hyphens, underscores) board: string · requiredDefault: "Selfhost"Length: 0 to 255 characters
Existing administrator API key api_key: secret · requiredLength: 0 to 4096 characters

Save onboarding.json, replace example values and supply env: secrets privately through your shell. Empty apps adds no links; add explicit links when this profile supports them.

{
  "mode": "bootstrap",
  "inputs": {
    "username": "admin",
    "password": "env:SELFHOST_PASSWORD",
    "board": "Selfhost"
  },
  "apps": []
}

selfhost app --directory ./homarr setup homarr
selfhost app --directory ./homarr setup-plan homarr onboarding.json
selfhost app --directory ./homarr setup-apply homarr onboarding.json --revision REVIEWED_REVISION

Setup modes, secret references and recovery

Keep service links current

Save your explicit new links as links.json, then review and sync whenever you need to. No scheduler is required.

selfhost app --directory ./homarr sync-plan homarr links.json
selfhost app --directory ./homarr sync homarr links.json --revision REVIEWED_REVISION

Tasks, triggers and link examples

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (14)

Public URL base-url: string
Login providers auth-providers: Retain credentials until OIDC access is verified. stringChoices: credentials, credentials,oidc, oidc, credentials,ldap, ldap
Session duration session-duration: Examples: 30m, 12h, 7d. string
OIDC issuer oidc-issuer: string
OIDC client ID oidc-client: string
OIDC secret oidc-secret: secret
Manage OIDC groups in Homarr oidc-local-groups: Enable to keep group membership managed by Homarr administrators. Disabling resumes group synchronization from the IdP. stringChoices: true, false
Group claim oidc-groups: string
LDAP URL ldap-uri: Prefer verified LDAPS for remote connections. string
LDAP base DN ldap-base: string
LDAP bind DN ldap-bind: string
LDAP bind password ldap-password: secret
Disable outbound integrations external-connections: Disables internet-dependent features such as feeds and weather. stringChoices: true, false
Log level log-level: stringChoices: debug, info, warn, error

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./homarr config homarr
selfhost app --directory ./homarr plan homarr changes.json
selfhost app --directory ./homarr apply homarr changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

Identity provider login

Selfhost can register a client with a supported provider and configure this app. Callback path: /api/auth/callback/oidc.

No administrator role is assigned by Selfhost. Check the app’s first-login policy and retain a local recovery account.

Save connection.json and replace the URLs. Supply SELFHOST_IDP_TOKEN privately in your shell.

{
  "provider": "zitadel",
  "issuer": "https://identity.example.com",
  "app_url": "https://app.example.com",
  "name": "Homarr"
}

selfhost app --directory ./homarr connect-account homarr connection.json
selfhost app --directory ./homarr connect-plan homarr connection.json
selfhost app --directory ./homarr connect homarr connection.json --revision REVIEWED_REVISION

Test sign-in in a separate browser session. HTTPS domains and HTTP loopback development origins are supported by Selfhost; the chosen app and provider must also accept the resulting callback. Provider permissions, localhost and recovery.

Database placement

This recipe supports postgres, mysql, mariadb. Workspace projects can choose a dedicated database, a shared source with a separate database and account, or an existing external database before their first start.

postgres adapter TLS modes: disable, require, verify-full. Use a private network for connections with TLS disabled.
mysql adapter TLS modes: disable. Use a private network for connections with TLS disabled.
mariadb adapter TLS modes: disable. Use a private network for connections with TLS disabled.

Standalone directories use the generated Compose and environment files directly. Configure the database there before first start. Selfhost’s source provisioning commands belong to workspace projects and are optional.

Database setup, CLI commands and backups

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

homarr: ghcr.io/homarr-labs/homarr:v1.77.2

1.77.2 ghcr.io/homarr-labs/homarr:v1.77.2
Local Docker initialization, private API key, board creation and incremental service links verified. Other platforms and provider login require separate validation.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Homarr documentation