Run with Docker Compose

The repository ships a compose file, deploy/compose.yaml, with the Homestead service, one data volume, and an optional Caddy reverse proxy for TLS. Its build: section builds the image from the repository root, so it works before any image is published.

Before you start

Docker with Docker Compose, Git, and a clone of the repository:
Terminal window
```
git clone https://github.com/aprajnaparamita/homestead.git
```
Run the commands below from the repository root (the homestead folder).

Set the base URL

Open deploy/compose.yaml. The service sets:

environment:
  HOMESTEAD_BASE_URL: https://home.example.com

HOMESTEAD_BASE_URL is the public address Homestead puts in share links, QR codes and agent setup snippets. It also decides whether sign-in cookies are marked secure, and which origin the browser must be on when it saves changes.

Only using it at home for now? Delete the line, and the environment: line too if nothing else is left under it. Homestead then uses the address you open it at.
Behind a proxy or tunnel? Set it to the exact address people will type, such as https://home.example.com.

If it doesn’t match the address in your browser, sign-in or saving fails. See Troubleshooting.

Start

Build the image and start the service.

docker compose -f deploy/compose.yaml up -d --build

Check that it’s healthy.

curl http://localhost:8080/api/v1/health

Start the web app from the same checkout, then open http://localhost:5173/setup and follow First run. The Quick start shows the two commands.

The service restarts on its own (restart: unless-stopped).

Everyday commands

The compose project is called homestead, so the container gets a generated name. Use the service name with docker compose instead of docker:

docker compose -f deploy/compose.yaml logs -f homestead

docker compose -f deploy/compose.yaml exec homestead homestead backup --out /tmp/family.tar.gz

docker compose -f deploy/compose.yaml down

down stops and removes the container but keeps the data volume. Don’t add -v unless you mean to delete the household.

To update to the latest main, pull and rebuild:

git pull

docker compose -f deploy/compose.yaml up -d --build

Database migrations run on their own when the server starts. Take a backup before updating.

Other settings

Add any of these under environment:. The full list is in Configuration.

Variable	Default	Meaning
`HOMESTEAD_LISTEN`	`:8080`	Listen address
`HOMESTEAD_DATA_DIR`	`/data`	Database, media and secret key
`HOMESTEAD_BASE_URL`	from the request	Public URL for links, QR codes and snippets
`HOMESTEAD_MDNS`	`true`	Announce `_homestead._tcp` on the LAN
`HOMESTEAD_TRUSTED_PROXIES`	empty	Comma-separated CIDRs allowed to set `X-Forwarded-*`
`HOMESTEAD_LOG_LEVEL`	`info`	`debug`, `info`, `warn` or `error`

LAN discovery for the phone app

The phone app can find Homestead on your Wi-Fi, but only if the container can reach the LAN’s multicast group. In the default bridge network it can’t, so discovery is silent. On Linux, run on the host network: in deploy/compose.yaml, remove the ports: block and uncomment

network_mode: host

then run up -d --build again. Host networking is Linux only.

TLS with Caddy

The compose file has a caddy service in an optional profile. It uses deploy/Caddyfile.example.

Edit deploy/Caddyfile.example and replace home.example.com with your own name. Point that name’s DNS records at this machine. Ports 80 and 443 must reach it.
Set HOMESTEAD_BASE_URL in deploy/compose.yaml to the same https:// address.

Start both services with the profile.

docker compose -f deploy/compose.yaml --profile caddy up -d --build

Caddy gets and renews certificates on its own. The example limits request bodies to 50 MB, matching Homestead’s upload limit, and sends Strict-Transport-Security.