Docker
Docker Compose is the recommended installation method. Install Docker Engine and the Compose plugin.
Docker Compose
First, create a docker-compose.yml file with the following content:
#---------------------------------------------------------------------## Homarr - A simple, yet powerful dashboard for your server. ##---------------------------------------------------------------------#services: homarr: container_name: homarr image: ghcr.io/homarr-labs/homarr:latest restart: unless-stopped volumes: - /var/run/docker.sock:/var/run/docker.sock # Optional, only if you want docker integration - ./homarr/appdata:/appdata environment: - SECRET_ENCRYPTION_KEY= ports: - '7575:7575' Encryption key
The SECRET_ENCRYPTION_KEY above is randomly generated by your browser. You can also generate one with openssl rand -hex 32.
Start Homarr from the directory containing docker-compose.yaml:
docker compose up -dPersist /appdata; it contains the database and configuration. Mount the Docker socket only when Homarr needs Docker
discovery or management.
Integration URLs must be reachable from the Homarr container. Browser-facing app URLs may use a different hostname; see Managing integrations.
Update
Back up before upgrading from v1 to v2. v2 migrates the existing database in place. For SQLite, this is
/appdata/db/db.sqlite by default; v1 cannot use the upgraded database. Switching back to the v1 image alone is not a
rollback. Image-rollback tools that revert only the container image do not restore the database; you still need
the pre-upgrade backup.
Stop Homarr before copying the complete /appdata directory or volume. Keep the pre-upgrade copy, your container
configuration, and SECRET_ENCRYPTION_KEY securely. If you use an external PostgreSQL database, back it up with its
native tools as well. See Backup and restore.
Update the image and recreate the container with the same configuration. Homarr runs database migrations automatically
at startup, including when moving from v1 to v2; no separate upgrade procedure is needed. Keep the /appdata mount and
SECRET_ENCRYPTION_KEY unchanged. Workshop connects to the production service by default.
Existing MySQL installations must convert to SQLite before upgrading to v2.
docker compose pull
docker compose up -dTo roll back, stop v2, restore the pre-upgrade database and /appdata backup with the matching configuration and
encryption key, then start the previously used v1 image. A backup taken after v2 has migrated the database cannot
restore v1 compatibility.
Board sizing after upgrading to v2
v2 uses fixed 200 × 200 logical-pixel cells and scales the whole board to fit the available width. A migrated
12-column layout can therefore show smaller widgets and text than in v1. Reducing the column count in
board layout settings makes cells appear larger at the same viewport
width; choose a count that fits your content.
Back up before changing columns: reducing the count can resize Containers and displace widgets. Check the layout in edit mode before saving. In v2.0.0, increasing the count again may not restore the previous arrangement after widgets or Containers have been displaced or resized; keep a backup rather than relying on reversing the column change.
Uninstall
docker compose down removes the containers and Compose network. Delete the configured /appdata host directory or
volume only when the Homarr data is no longer needed.
Docker CLI
The equivalent standalone container is:
docker run \
--name homarr \
--restart unless-stopped \
-p 7575:7575 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /absolute/path/to/homarr/appdata:/appdata \
-e SECRET_ENCRYPTION_KEY='your_64_character_hex_string' \
-d ghcr.io/homarr-labs/homarr:latestRemove the Docker socket mount when it is not required. To update, follow the backup guidance above, pull
the current image, recreate the container with the same arguments, and keep the /appdata mount and
SECRET_ENCRYPTION_KEY unchanged.