Configuration

Main settings in .env:

Variable	Default	Description
ADMIN_TOKEN	abc123 (dev only)	Bearer token with admin rights on the API
ADMIN_USER, ADMIN_PASSWORD	admin, —	The local admin account of the UI
SESSION_SECRET	—	Signs the session cookie; a long random string
HOST_DOMAIN	lvh.me	Every address is under it: the UI, the registry, the sandbox apps (needs a wildcard DNS record)
HOST_ADDRESS	localhost	The host's address, put into the sandbox TLS certificates and used for the registry token URL when PUBLIC_URL is not set
PUBLIC_URL	http://p7y.<HOST_DOMAIN>	The address of the UI as users see it; https://… turns on the HTTPS checks (see HTTPS)
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_PROVIDER_NAME	—	Sign-in for everyone but the admin (see Web UI and sign-in)
OIDC_ALLOWED_DOMAINS, OIDC_ALLOWED_EMAILS	— (anyone)	Who may sign in with OIDC, as comma lists: domains (example.com,partner.org, the exact domain, not its subdomains) and single addresses (guest@gmail.com). Without either, anyone with an account at the provider can sign in, with Google any Google account; Purgatory says so in its log at startup. Checked at sign-in and on every request: someone taken off the list (after a restart) is signed out and their tokens stop working at once. The admin is never limited
SANDBOX_QUOTA	3	Sandboxes a user may have running at once; asleep and deep-sleeping ones are not counted; 0 = unlimited
SANDBOX_QUOTA_MAX	(empty)	How many a user may have running while the server has room, above the guaranteed SANDBOX_QUOTA (e.g. 10). Above the guarantee a new sandbox, or one woken, needs room to spare: every other owner must still be able to reach their guarantee (their running sandboxes hold their places already), and so must one newcomer. Waking from plain sleep takes no new place, so only this maximum counts. Nobody is ever put to sleep to make room. Empty: nothing above SANDBOX_QUOTA; 0: no maximum
FILES_MAX_UPLOAD	100m	The largest file the Files tab (and PUT /sandboxes/:name/files/content) takes, like 512m or 1g. Every request body is read into memory first, so this (plus 1 MB) is also the cap on any request: a larger one gets 413
SANDBOX_MAX_TOTAL	200	Running sandboxes on the whole server, the admin's included; asleep, deep-sleeping and archived ones take no place, so letting a sandbox sleep frees it for everyone. When it is reached nobody but the admin can create one or wake one: the admin is never refused, but its running sandboxes take places too; 0 = no limit. Each sandbox, asleep too, keeps a Docker network until it goes into deep sleep: the host's Docker address pools must have room for them (see check-host.sh)
DEFAULT_RUNTIME	auto	Runtime for new sandboxes when a request names none: auto picks sysbox where the host has sysbox installed (no privileged container) and dind otherwise; or name one (see Runtimes and templates)
ALLOWED_RUNTIMES	— (all)	Runtimes new sandboxes may use, as a comma list: sysbox forbids the privileged dind on a shared server. Others are left out of GET /runtimes and the New sandbox form, and a create asking for one is a 400 (so is one without a runtime when the default is not allowed). Existing sandboxes keep running, sleeping and waking
SANDBOX_CPUS, SANDBOX_MEMORY	2, 4g	CPU and memory limit of every new sandbox (see CPU and memory)
SANDBOX_MAX_CPUS, SANDBOX_MAX_MEMORY	4, 8g	How far a user can raise their sandbox's limits; the admin can go up to the host
SANDBOX_DISK	20g	Disk use above which a sandbox is flagged; a warning only, see Disk
LOGIN_CAPACITY	on	The sign-in page shows the sandbox places on the server: taken and free of SANDBOX_MAX_TOTAL, with a bar (orange from 90%, red when full). The page is public, so off hides it; nothing is shown without a server limit. Counted at most every 30 seconds
GITHUB_STATS	on	The topbar links to the GitHub repo and shows Purgatory's version, stars and forks. The server fetches the counts at most once an hour (users' browsers never contact GitHub); off never asks GitHub, and the link and the version stay
DEFAULT_TEMPLATE	starter	Template for new sandboxes when a request names none. An old value such as dind-standard makes every create without a template fail with Unknown template
DEEP_SLEEP_CHECK_INTERVAL	1m	How often Purgatory looks for sandboxes to take into deep sleep
HOST_SANDBOXES_DIR	auto-detected	Host path of opt/sandboxes (every sandbox's compose file mounts from it). Set it only if auto-detection fails; an old HOST_USERS_DIR (the former opt/users) still works, its sibling sandboxes is used
P7Y_API_BIND	0.0.0.0	Interface of the direct API port 8081; 127.0.0.1 for a public deployment
P7Y_VERSION	the release the docker-compose.yml came from	The image version to run. Pin it only to stay on a version: an upgrade with a new docker-compose.yml then needs it changed too
REGISTRY_PUBLIC_PULL	true	Images whose versions all passed the secret scan can be pulled without a login; false: tokens only