Configuration

Documentation · Português

Loading and validation

The source of truth is config/environment.py, config/engine.py, config/settings.py and .env.example. Settings load once at process startup. Exported variables take precedence over .env; interpolation is disabled, so ${VALUE} remains literal. Relative paths resolve against the source root; ~ expands to the service user's home.

Booleans accept 1/true/yes/y/on and 0/false/no/n/off, case-insensitively. Invalid spellings fail startup. Engine numeric limits must be positive. Join-code minimum ≤ default ≤ maximum, and viewport area cannot exceed width × height. GRAVEWRIGHT_PORT must be 1–65535. Public origins normalize the scheme and hostname to lowercase, preserving explicit ports and IPv6 brackets; HTTPS://VTT.EXAMPLE.COM therefore enables the same HTTPS settings as https://vtt.example.com. They reject paths, trailing slashes, credentials, empty ports, control characters, query strings and fragments, including empty ? or # delimiters. These validations do not imply that every setting has the same numeric parser or upper bound.

The Windows runner reads defaults from .env.example, then .env in the project root, with local security settings enforced by its dedicated profile. If the project .env is missing, it generates a complete configuration from .env.example with a new private secret. It never imports configuration from user-data directories. The reference below describes the standard server settings; feature settings also apply to the runner, while its bind address, debug, cookies, host/origin, proxy trust and single-process Channels choices are fixed for local execution. Set the runner's port in the project .env.

Environment reference

Values below match the sample/default configuration. An empty cell shown as “empty” means no configured value. Byte values use binary units in explanations.

The native installer configures the official Marketplace automatically when no catalog is configured. Existing custom catalogs are preserved.

Two optional commented settings are also recognized:

GRAVEWRIGHT_CONTAINER is read by release discovery to label the install format when set to 1, true or yes; it does not configure a container runtime or provide automatic updates. DJANGO_SETTINGS_MODULE selects the Python settings module; entry points default to config.settings.

Blueprint Delay worker

The ASGI host starts the Delay worker automatically. Daphne uses its reactor startup/shutdown hooks, including normal Runner execution; other ASGI hosts must deliver lifespan startup/shutdown events. Importing Django or running a management command does not start a scheduler. The worker checks due database rows every 250 ms, processing at most 20 per pass; actual execution can be later under load or after downtime. It does not require connected browsers, HTTP polling, Redis jobs or a separately launched process.

Pending waits live in the configured SQLite database and survive a server restart. GRAVEWRIGHT_AUTOMATION_WORKER_ENABLED=false disables processing for that process without discarding the queue. Scene-level Pause automation instead holds only that scene's waits until resume. The updater's existing managed maintenance flag holds the queue through health verification until the update is committed or rolled back. Apply the normal migrations before starting the host; the worker reports database failures in server logs and retries, rather than treating them as successful executions. See Persistent Delay for cancellation and copying.

Map tiling and large images

GRAVEWRIGHT_MAP_MAX_PIXELS is the exact map pixel limit. At startup, Pillow's header guard is raised to at least that configured value so it does not impose an unrelated lower limit. Exceeding either pixel guard reports a pixel-limit error. The independent byte, dimension and tile-count limits still apply. Both pixel settings must be positive; restart the server after changing them.

GRAVEWRIGHT_MAP_TILER=auto uses libvips when available and otherwise uses Pillow. pillow always selects Pillow; vips requires libvips and fails startup when it is unavailable. The default dependencies and native installers do not select the optional vips extra. For a source environment, install it with:

uv sync --locked --extra vips

For a native Runner, install into the Python environment named by its generated launcher; the checkout's .venv may be a different environment. Keep --extra vips on subsequent dependency syncs. A plain exact uv sync, a native reinstall or preparation for a managed core update selects the default dependencies and can remove or omit the extra. Check availability again after those operations; setting GRAVEWRIGHT_MAP_TILER=vips does not install dependencies.

Pillow decodes the entire map. Its additional GRAVEWRIGHT_MAP_PILLOW_MAX_PIXELS ceiling defaults to 64 million pixels, even if the overall map limit is higher. A larger image requires libvips or an explicit increase to that ceiling after assessing available memory. This pixel ceiling bounds accepted image size, not resident memory: decoding, orientation, resampling and codecs also allocate memory. Libvips streams ordinary maps in strips, but formats, codecs and EXIF rotations can require additional memory and temporary disk space.

Only one map pyramid is generated at a time per server process, including decoding. Separate workers can still process maps concurrently. Both engines produce lossless WebP tiles with the same 512-pixel layout and partial edge tiles; reduced levels can differ because the resampling filters differ.

Native tiling stages the source image and generated tiles under installation-root data/runner/tmp/. An explicit GRAVEWRIGHT_RUNNER_ROOT changes the tool root, and a Django FILE_UPLOAD_TEMP_DIR override takes precedence for tiling scratch space; relative paths resolve against the installation root. The directory must be writable and have room for the source, staged tiles and any codec spill files while final tiles are saved to media storage. Storage or native generation failures remain server errors, and already saved tiles are removed if the upload fails. See deployment for synchronous upload timeouts and capacity planning.

Settings without environment switches

The following are configured in Python, not loaded automatically from similarly named .env entries:

Authentication bodies are separately limited to 16 KiB in middleware. Archive imports/exports have limits in gravewright/administration/archives.py. Map uploads have independent byte, decoded-image and generated-tile bounds. Check the owning code before assuming one limit governs every path.

Persisted host preferences

gravewright.administration.preferences stores app identity, update channels and privacy content in the HostSettings singleton. APP_NAME and DEFAULT_LOCALE provide fallbacks, not forced overrides of every saved value. The supported locale list is currently ('en',). Setting DEFAULT_LOCALE=pt-BR does not add a Portuguese UI.

Privacy publication is enabled when either the environment flag or the stored privacy flag is true. Snapshot/audit retention is enforced by the relevant operation paths, not a background scheduler supplied by this project. User preferences and campaign settings are separate from these host settings.

For HTTPS, set the exact browser-facing public origin, including any non-default port. Other entries in DJANGO_ALLOWED_HOSTS do not become additional permitted WebSocket origins when a public origin is configured. Without it, WebSocket validation derives the origin from the ASGI scheme and Host; an absent scheme defaults to HTTP.

The ASGI proxy adapter accepts exactly one X-Forwarded-Proto header with value http or https only from the immediate socket peer in TRUSTED_PROXIES. It ignores duplicate, comma-separated, malformed or untrusted values. Keep Daphne's --proxy-headers disabled so the original peer remains available for this check. The same trust list controls client-IP forwarding. See deployment for a TLS proxy example, Redis and storage requirements.