Run Savorum with Docker

Docker is the easiest way to run Savorum yourself. This page covers where your data lives, how to upgrade, and the settings you’ll change before sharing it. From a copy of the savorum repository, one command builds and starts it:

docker compose up --build -d

Then visit http://127.0.0.1:8080 on the same computer. The included Compose file opens Savorum on that computer only, keeps your data in the savorum-data volume, and makes the rest of the container read-only.

Use a released image

Released images are published as ghcr.io/savorum/savorum. Pin a full version, such as v0.1.0, rather than latest, so Savorum only changes when you decide:

SAVORUM_IMAGE=ghcr.io/savorum/savorum:v0.1.0 docker compose up --no-build -d

To upgrade:

1. Make and verify a backup.
2. Change the version in SAVORUM_IMAGE.
3. Run the same command again.

If an upgrade fails, see Upgrade Savorum.

Where your data lives

Savorum keeps everything in the volume mounted at /data: the database at /data/savorum.db and your photos and files in /data/assets. It runs as user and group 65532.

Add other SAVORUM_* settings under environment: in the Compose file. If you change the published port, set SAVORUM_PUBLIC_URL to match the address people use. Savorum refuses requests for any other address.

To use a folder on the host instead of the volume, create it first, owned by 65532:65532 with mode 0700. If several host accounts must share it, use a dedicated group, a 0770 setgid folder, and SAVORUM_STORAGE_ACCESS=group. Don’t run the image as root or make the folder world-readable to get around ownership.

Write backups to a separate mounted folder, not inside /data.

Turn on sign-in

The container is only reachable from the host, so the default local mode is safe while you try it out. Before opening it up, create an administrator inside the running container. The password comes from a mounted secret file:

docker compose exec -T savorum /savorum user create-admin \
  --database /data/savorum.db --login chef \
  --password-file /run/secrets/savorum-admin-password

Keep that file readable only by 65532, and remove it once the account exists. The command prints the account’s user ID, never the password.

Then set SAVORUM_AUTH_ENABLED=true and SAVORUM_PUBLIC_URL under environment:, and restart the service. A running container doesn’t pick these up. Passkeys are tied to that address, so choose it before people add them. Accounts and access covers the rest.

PDF and photo import

The default image doesn’t include the tools to import PDFs and photos. The documents build target makes a larger image that adds them, with English text recognition:

docker build --target documents -t savorum:documents .
SAVORUM_IMAGE=savorum:documents docker compose up --no-build -d

It keeps the same user, /data volume, port, and health check.

Check the setup

1. Open http://127.0.0.1:8080 and create a recipe.

2. Run docker compose restart savorum and confirm the recipe is still there.

3. Run the health check:

   docker compose exec -T savorum /savorum healthcheck

4. Practice a backup and restore into a second, empty volume, as described in Restore a Compose deployment.

Good to know

• Savorum limits memory for each import and print, but not for the container as a whole. Set a container memory limit, such as mem_limit in Compose, especially with the document-tools image or when other people can upload files.
• docker stop gives Savorum 30 seconds to shut down cleanly. Don’t wrap the entrypoint in a shell script that swallows the stop signal.
• Because the container is read-only, each start prepares the print typesetter again on the first print. To keep it, mount a small writable volume owned by 65532 and point XDG_CACHE_HOME at it.
• To open Savorum from other devices, keep the container private and follow Secure remote access.

Next: Turn on sign-in and invite people.