Configuration

The server is configured with environment variables.

Installed with	Settings live in	Apply changes
The Linux installer	/etc/whittle/whittle.env	sudo systemctl restart whittle (Alpine: sudo rc-service whittle restart)
Docker	-e NAME=value or --env-file	recreate the container
Docker Compose	environment: in docker-compose.yml	docker compose up -d

All settings

Variable	Default	What it does
WHITTLE_BIND	0.0.0.0:8080	Address and port to listen on. PORT=9000 also works. Use 127.0.0.1:8080 when a reverse proxy runs on the same machine.
WHITTLE_AUTH	local	How people sign in: local, oidc, local,oidc or none. See below.
WHITTLE_SIGNUP	false	true lets anyone who can reach the server create an account. The first account is always allowed and becomes the administrator.
WHITTLE_PUBLIC_URL		The address people type, e.g. https://cad.example.com. Required for single sign-on. When it starts with https://, cookies are marked Secure.
WHITTLE_SECURE_COOKIES	on if the public URL is https://	Force Secure cookies true or false.
WHITTLE_DATA	/var/lib/whittle (installer), /data (Docker)	Designs, thumbnails and the SQLite database.
WHITTLE_DATABASE_URL	SQLite inside WHITTLE_DATA	Use PostgreSQL instead, e.g. postgres://whittle:secret@localhost:5432/whittle.
WHITTLE_WEB	/opt/whittle/web (installer), /srv/whittle (Docker)	The web app's files. You won't normally change this.
WHITTLE_MAX_UPLOAD_MB	64	Largest design that can be saved, in MB.
WHITTLE_MAX_VERSIONS	50	Versions kept per design; the oldest are removed beyond this.
WHITTLE_SESSION_DAYS	30	How long people stay signed in.
WHITTLE_OIDC_ISSUER		Single sign-on: your provider's issuer URL.
WHITTLE_OIDC_CLIENT_ID		Single sign-on: client ID.
WHITTLE_OIDC_CLIENT_SECRET		Single sign-on: client secret (leave empty for a public client).
WHITTLE_OIDC_NAME	Single sign-on	Label on the sign-in button, e.g. Authentik or Google.
WHITTLE_OIDC_SCOPES	openid email profile	Scopes to request.
WHITTLE_OIDC_AUTO_CREATE	true	Create an account the first time someone signs in with single sign-on. With false, an administrator must add them first.
RUST_LOG	info	Log detail: error, warn, info or debug.

If a setting is wrong, the server refuses to start and says which one (see the logs: journalctl -u whittle).

Sign-in modes

WHITTLE_AUTH	Who can use it	Good for
local (default)	People with a username and password stored on the server	Families, small teams, classrooms
oidc	People who can sign in to your identity provider	Organisations and homelabs with Authentik, Keycloak, Google Workspace, Microsoft Entra ID…
local,oidc	Both: two choices on the sign-in screen	Single sign-on plus a fallback admin account
none	Anyone who can reach the server. Everyone shares one workspace	A trusted home network, behind a VPN, or behind a proxy that already does authentication

How people get accounts (local): the first person to open a new server creates the administrator account. After that, an administrator adds people in Account ▸ Manage users (Users and Administration), or set WHITTLE_SIGNUP=true to let people sign up themselves.

Single sign-on setup, step by step: Single Sign-On.

PostgreSQL

SQLite is the default and is right for most installs, including teams of dozens. Use PostgreSQL if you already run it and back it up, or want the database on another machine.

-- as the postgres superuser
CREATE USER whittle WITH PASSWORD 'choose-a-password';
CREATE DATABASE whittle OWNER whittle;

WHITTLE_DATABASE_URL=postgres://whittle:choose-a-password@localhost:5432/whittle

Restart Whittle. Tables are created and upgraded automatically. Design files are still kept in WHITTLE_DATA, so back up both. If the password contains special characters such as @, : or /, percent-encode them (@ → %40).

Tested with PostgreSQL 16; any currently supported PostgreSQL release should work.

Example settings file

WHITTLE_BIND=127.0.0.1:8080
WHITTLE_PUBLIC_URL=https://cad.example.com
WHITTLE_AUTH=local,oidc
WHITTLE_SIGNUP=false
WHITTLE_OIDC_ISSUER=https://auth.example.com/application/o/whittle/
WHITTLE_OIDC_CLIENT_ID=whittle
WHITTLE_OIDC_CLIENT_SECRET=paste-the-secret-here
WHITTLE_OIDC_NAME=Authentik
WHITTLE_DATA=/var/lib/whittle
WHITTLE_WEB=/opt/whittle/web
RUST_LOG=info,tower_http=warn,sqlx=warn