One container. Your hardware.

Install with Docker Compose

Download the Compose file of the current release into a directory on your Docker host. It is pinned to that release's image. To follow latest instead, use docker-compose.yml from the repository. Then run from that directory:

curl -fsSLo docker-compose.yml https://github.com/bifrost0x/homegrid/releases/download/v0.1.0/docker-compose-0.1.0.yml
docker compose up -d --wait
docker compose ps

Open http://<docker-host-ip>:8095 from your network, or http://localhost:8095 on the Docker host, and create the administrator account. There are no default credentials. Complete setup from a trusted network before exposing the installation more broadly.

The Compose file pulls the public image ghcr.io/bifrost0x/homegrid. It runs the container as UID/GID 65532 with a read-only root filesystem, a temporary /tmp, dropped capabilities and no-new-privileges. Only /data is writable. The Docker socket is not mounted, and a fresh named volume needs no permission changes.

Running Portainer? Paste the Compose file into a stack. The Docker guide covers stack variables and troubleshooting.

Configuration

Create a .env file beside docker-compose.yml. Compose reads it for variable interpolation; apply changes with docker compose up -d --wait. A plain restart does not pick up changed settings.

The native executable reads process environment variables and does not load .env files on its own.

LAN access and HTTPS

By default Compose publishes HomeGrid on every host interface at port 8095, subject to the host firewall. To keep it local to the Docker host, set:

HOMEGRID_BIND_ADDRESS=127.0.0.1
HOMEGRID_PORT=8095

Direct port access uses plain HTTP. For access over an untrusted network, put HomeGrid behind an HTTPS reverse proxy and enable secure cookies:

HOMEGRID_BIND_ADDRESS=127.0.0.1
HOMEGRID_SECURE_COOKIE=true

• Preserve Host and Origin. HomeGrid validates the browser-facing hostname and port. Forward the public Host unchanged, including a non-default port, and keep the browser's Origin header intact. X-Forwarded-Host and X-Forwarded-Proto are not needed and cannot override this check.
• Trusted proxies are optional. Plain HTTPS termination works without HOMEGRID_TRUSTED_PROXIES. Set it only when you want forwarded client IPs for rate limiting, and only to addresses you control. Left empty, forwarded client IPs are ignored.
• Pick a reachable binding. A proxy on the same host can use the loopback binding above. A proxy in another container needs a shared Docker network or a reachable host binding.

If sign-in reports an address or origin error, check that the proxy does not replace Host with the upstream container name or port.

Updates and version pinning

latest is a moving tag that follows the main branch. For repeatable deployments, pin a release tag or an image digest in .env:

HOMEGRID_IMAGE=ghcr.io/bifrost0x/homegrid:0.1.0
# or: HOMEGRID_IMAGE=ghcr.io/bifrost0x/homegrid@sha256:<digest>

Available versions and their digests are listed on the releases page. To update:

1. Make a full backup of the stopped data volume (see below).
2. Change the pinned version, if you use one, and run docker compose pull.
3. Run docker compose up -d --wait and check docker compose logs.

Database migrations run at startup. Schema downgrades are not supported: to roll back, start the previous image with a restored pre-upgrade volume.

Backups

Portable JSON export

Settings → Backup exports applications, categories and appearance as JSON. The export excludes passwords and sessions and references uploaded images by path without embedding them. Imports also accept Homepage, Homer and Dashy configurations, show a preview and offer merge or replace. Find unused images lists uploads that nothing uses anymore and deletes them after you confirm. Exports can reveal internal service names and addresses, so treat them as sensitive.

Full data-volume backup

The named volume holds the database, uploaded files and the administrator account. Stop HomeGrid for the entire copy: copying only homegrid.db from a running SQLite database is not a complete backup. The Docker guide provides tested commands that create a private archive and restore it into a new volume, leaving the original untouched until you have verified the result.

Uninstall

From the Compose directory, docker compose down removes the container and network and keeps your data volume. You can start again later with docker compose up -d --wait.

Afterwards, remove the image with docker image rm ghcr.io/bifrost0x/homegrid:latest (or the tag you pinned).