Docker

Whittle's server is published as a Docker image for linux/amd64 and linux/arm64:

ghcr.io/anand34577/whittle with tags latest, 0.2, 0.2.0, …

It works with Docker, Docker Desktop (Windows, macOS), Podman, Portainer, Unraid, TrueNAS, Synology Container Manager and anything else that runs containers.

One line

docker run -d --name whittle -p 8080:8080 -v whittle-data:/data --restart unless-stopped ghcr.io/anand34577/whittle:latest

Open http://<this machine>:8080/ and create the first account. It becomes the administrator.

Docker Compose

curl -fsSLO https://raw.githubusercontent.com/anand34577/whittle/main/deploy/docker-compose.yml
docker compose up -d

The compose file has commented sections for PostgreSQL and common settings. Or write your own:

services:
  whittle:
    image: ghcr.io/anand34577/whittle:latest
    restart: unless-stopped
    ports: ["8080:8080"]
    volumes: [whittle-data:/data]
    environment:
      WHITTLE_AUTH: local
volumes:
  whittle-data:

Settings

Pass any setting from Configuration as an environment variable:

docker run -d --name whittle -p 8080:8080 -v whittle-data:/data \
  -e WHITTLE_AUTH=local,oidc \
  -e WHITTLE_PUBLIC_URL=https://cad.example.com \
  -e WHITTLE_OIDC_ISSUER=https://auth.example.com/application/o/whittle/ \
  -e WHITTLE_OIDC_CLIENT_ID=whittle \
  -e WHITTLE_OIDC_CLIENT_SECRET=... \
  ghcr.io/anand34577/whittle:latest

Or keep them in a file: --env-file whittle.env (a template is in deploy/whittle.env.example; in a container, leave WHITTLE_BIND, WHITTLE_WEB and WHITTLE_DATA out, the image sets them).

Data

Everything lives in /data inside the container: the SQLite database and every design version. A named volume (as above) is simplest.

To use a folder on the host instead (-v /srv/whittle:/data), give it to the container's user first:

sudo mkdir -p /srv/whittle
sudo chown -R "$(docker run --rm ghcr.io/anand34577/whittle:latest id -u)" /srv/whittle

Back it up: see Backups and Upgrades.

Updating

docker pull ghcr.io/anand34577/whittle:latest
docker rm -f whittle
docker run -d --name whittle -p 8080:8080 -v whittle-data:/data --restart unless-stopped ghcr.io/anand34577/whittle:latest

With Compose: docker compose pull && docker compose up -d. The database upgrades itself on start.

To stay on a release line, use a version tag such as ghcr.io/anand34577/whittle:0.2 instead of latest.

Commands inside the container

docker exec -it whittle whittle-server user list
docker exec -it whittle whittle-server user add ada --admin       # then type the password and press Enter
docker exec -it whittle whittle-server user passwd ada

See Users and Administration.

Health check

The image has a built-in health check (/api/health), so docker ps shows healthy once it's ready.