Quick start

You’ll build the Homestead image from the source code, start one container, run the web app next to it and finish setup in your browser. It takes a few minutes, most of it the first build.

Before you start

A computer that can run Docker: a Linux server, a NAS, a Raspberry Pi (arm64), or your own Mac or PC. The image builds for amd64 and arm64.
Docker, with Docker Compose if you want the Compose tab below.
Git.
Node 22 and pnpm 9, for the web app (the versions pinned in mise.toml).
Ports 8080 and 5173 free on that machine.

Get the source code.

git clone https://github.com/aprajnaparamita/homestead.git

Go into the folder.
Terminal window
```
cd homestead
```
Build the image from the repository root. The first build downloads Node and Go build images and can take several minutes.
Terminal window
```
docker build -f deploy/Dockerfile -t homestead .
```
Start the container. Everything your household owns goes into the homestead-data volume.
Terminal window
```
docker run -d --name homestead -p 8080:8080 -v homestead-data:/data homestead
```

Get the source code.

git clone https://github.com/aprajnaparamita/homestead.git

Go into the folder.
Terminal window
```
cd homestead
```
Open deploy/compose.yaml and look at HOMESTEAD_BASE_URL. It is set to the example https://home.example.com. If you’ll open Homestead at http://localhost:8080 for now, delete that line, and the environment: line above it if nothing else is left under it. If you already have a public address, put it there instead. A wrong value stops sign-in cookies and saving from working.
Build and start. The compose file builds from the repository root.
Terminal window
```
docker compose -f deploy/compose.yaml up -d --build
```

With Compose, the container isn’t called homestead. Use docker compose -f deploy/compose.yaml logs homestead for logs and docker compose -f deploy/compose.yaml exec homestead homestead … for CLI commands. The Docker Compose guide has more.

Check that it’s running

Ask the health endpoint. It needs no login.

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

You should see "status":"ok". A local build reports "version":"dev". If the database can’t be reached, the status is degraded and dbOk is false.

Docker also runs this check itself every 30 seconds. docker ps shows the container as healthy once it passes.

Open the web app

Run these from the homestead folder you cloned. They install the JavaScript workspace and start the web app’s development server.

Install the workspace dependencies.
Terminal window
```
pnpm install --frozen-lockfile
```
Start the web app. Leave it running.
Terminal window
```
pnpm --dir web dev
```
Open http://localhost:5173/setup. If setup is already done, the page sends you to the login screen.

The development server only listens on this machine. To reach it from a phone or another computer on your network, start it with pnpm --dir web dev --host and use the machine’s address, such as http://192.168.1.20:5173. If you have Go installed too, make dev starts the server and the web app together.

Continue with First run.

The app’s docs name a published image for later. This command works only once that image exists, and the address may change at release:

docker run -d --name homestead -p 8080:8080 -v homestead-data:/data ghcr.io/homestead-app/homestead:latest

Stopping and starting

Your data stays in the volume when the container stops or is removed.

docker stop homestead

docker start homestead