Backup and restore

homestead backup writes one .tar.gz archive with everything your household owns:

a consistent snapshot of the SQLite database, taken with VACUUM INTO,
the media folder,
the secret key (secret.key), which decrypts stored API keys and signs media URLs.

The server can keep running while the backup runs. Everything in the archive is written with 0600 permissions.

Make a backup

These commands assume the container is called homestead, as in the Quick start. With Compose, replace docker exec homestead with docker compose -f deploy/compose.yaml exec homestead.

Write the archive inside the container.
Terminal window
```
docker exec homestead homestead backup --out /tmp/family.tar.gz
```
It reports the database size and the number of media files.

Copy it out to the host.

docker cp homestead:/tmp/family.tar.gz ./family.tar.gz

Remove the copy inside the container.
Terminal window
```
docker exec homestead rm /tmp/family.tar.gz
```
Store family.tar.gz somewhere off the server.

Restore a backup

homestead restore replaces the whole data directory with the archive’s contents. It refuses archives that aren’t Homestead backups. The server must be stopped while it runs, and it only replaces an existing household when you pass --force.

Stop the server.
Terminal window
```
docker stop homestead
```
Run the restore in a one-off container that mounts the same data volume and the folder holding your archive. The image’s entry point is homestead, so the command is just restore.
Terminal window
```
docker run --rm -v homestead-data:/data -v "$PWD":/backup homestead restore --force /backup/family.tar.gz
```
Leave out --force when restoring into a new, empty volume.
Start the server again.
Terminal window
```
docker start homestead
```

The container runs as user 10001, so that user must be able to read the archive through the mounted folder.

With Compose, stop with docker compose -f deploy/compose.yaml stop homestead. The compose project names the volume homestead_homestead-data and tags the image it builds ghcr.io/homestead-app/homestead:latest, so use those two names in the docker run line.

If the archive had no secret key, restore says so: stored API keys (such as an X API key) stay encrypted with the old key and must be entered again.

Check that it worked

curl http://localhost:8080/api/v1/health shows "status":"ok".
You can sign in with the same usernames and passwords, and your people and circles are back.

Other exports

A shared circle can be downloaded as a .homestead.json file and imported into any Homestead; see Share a circle.
Deleting the household entirely is deleting its volume. Back up first:
Terminal window
```
docker volume rm homestead-data
```

Running the binary directly

Outside Docker, the same commands read HOMESTEAD_DATA_DIR (default /data):

homestead backup --out family.tar.gz

homestead restore --force family.tar.gz

Flags can go before or after the archive name.