Environment Variables Reference¶
This page contains the complete reference for all configurable environment variables in Depictio.
Auto-generated Documentation
This documentation is auto-generated from the settings_models.py source file to ensure accuracy.
Quick Start¶
For most deployments, you only need to configure a few variables. See the Quick Start Guide for the minimal configuration.
# Minimal required configuration
DEPICTIO_BOOTSTRAP_ADMIN_EMAIL=admin@example.com
DEPICTIO_BOOTSTRAP_ADMIN_PASSWORD=changeme
DEPICTIO_S3_ROOT_PASSWORD=$(openssl rand -base64 12)
Complete Environment File
For a ready-to-use file with all variables, copy .env.complete.example to .env and uncomment the variables you need.
Variable Reference by Category¶
Quick Navigation¶
- FastAPI Backend
- React Viewer Frontend
- MongoDB Database
- S3 Storage
- Remote Data Sources
- Authentication
- Bootstrap
- Redis Cache
- Celery Task Queue
- Real-time Events
- Performance & Timeouts
- Backup & Restore
FastAPI Backend¶
Config Class: FastAPIConfig
Environment Prefix: DEPICTIO_FASTAPI_
Base class for service configurations with internal/external URL handling.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_FASTAPI_SERVICE_NAME |
depictio-backend |
- |
DEPICTIO_FASTAPI_SERVICE_PORT |
8058 |
- |
DEPICTIO_FASTAPI_EXTERNAL_HOST |
localhost |
- |
DEPICTIO_FASTAPI_EXTERNAL_PORT |
8058 |
- |
DEPICTIO_FASTAPI_EXTERNAL_PROTOCOL |
http |
- |
DEPICTIO_FASTAPI_PUBLIC_URL |
- | - |
DEPICTIO_FASTAPI_EXTERNAL_SERVICE |
false |
- |
DEPICTIO_FASTAPI_HOST |
0.0.0.0 |
- |
DEPICTIO_FASTAPI_WORKERS |
4 |
- |
DEPICTIO_FASTAPI_SSL |
false |
- |
DEPICTIO_FASTAPI_LOGGING_LEVEL |
INFO |
- |
DEPICTIO_FASTAPI_CORS_ALLOWED_ORIGINS |
(empty) | Allowed CORS origins — comma-separated list (e.g. https://app.example.com,https://example.com). Empty disables credentialed cross-origin requests. Wildcard * is rejected when used with credentials. |
DEPICTIO_FASTAPI_CORS_ALLOW_CREDENTIALS |
true |
Whether the CORS layer attaches credentials (cookies / Authorization header). |
Component export (v1.17.0+)¶
The API that serves one dashboard component to another website. See Component export and embedding.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_FASTAPI_EMBED_ENABLED |
false |
Serve /depictio/api/v1/export and show Export / embed on the tiles. Off, every export route answers 404 |
DEPICTIO_FASTAPI_EMBED_ALLOWED_ORIGINS |
(empty) | Sites allowed to frame an exported page, comma-separated. They become its CSP frame-ancestors. Empty: the pages open on their own but cannot be framed. * is refused |
DEPICTIO_FASTAPI_EMBED_CSP_UNSAFE_INLINE |
false |
Allow inline scripts in the exported page instead of listing their hashes |
React Viewer Frontend¶
Config Class: ViewerConfig
Environment Prefix: DEPICTIO_VIEWER_
Base class for service configurations with internal/external URL handling.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_VIEWER_SERVICE_NAME |
depictio-viewer |
- |
DEPICTIO_VIEWER_SERVICE_PORT |
80 |
Internal bind port (nginx inside the container) |
DEPICTIO_VIEWER_EXTERNAL_HOST |
localhost |
- |
DEPICTIO_VIEWER_EXTERNAL_PORT |
5080 |
Host-side port mapped to the viewer container |
DEPICTIO_VIEWER_EXTERNAL_PROTOCOL |
http |
- |
DEPICTIO_VIEWER_PUBLIC_URL |
- | - |
DEPICTIO_VIEWER_EXTERNAL_SERVICE |
false |
- |
DEPICTIO_VIEWER_HOST |
0.0.0.0 |
- |
DEPICTIO_VIEWER_WORKERS |
4 |
Gunicorn worker processes |
DEPICTIO_VIEWER_DEBUG |
true |
Debug mode with hot reload |
DEPICTIO_VIEWER_AUTO_GENERATE_FIGURES |
false |
Automatic figure generation in UI mode |
DEPICTIO_VIEWER_INSPECTOR_ENABLED |
false |
Docked component inspector, replacing the per-component popovers for advanced-visualisation controls, notes and metadata. Experimental (v1.4.0+) |
DEPICTIO_VIEWER_DASHBOARDS_DEFAULT_VIEW |
table |
View /dashboards opens in for someone who never picked one: thumbnails or table. A view chosen in the browser, or named by a shared link, wins (v1.11.2+; the default was thumbnails until v1.12.0) |
MongoDB Database¶
Config Class: MongoDBConfig
Environment Prefix: DEPICTIO_MONGODB_
Base class for service configurations with internal/external URL handling.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_MONGODB_SERVICE_NAME |
mongo |
- |
DEPICTIO_MONGODB_SERVICE_PORT |
27018 |
- |
DEPICTIO_MONGODB_EXTERNAL_HOST |
localhost |
- |
DEPICTIO_MONGODB_EXTERNAL_PORT |
27018 |
- |
DEPICTIO_MONGODB_EXTERNAL_PROTOCOL |
http |
- |
DEPICTIO_MONGODB_PUBLIC_URL |
- | - |
DEPICTIO_MONGODB_EXTERNAL_SERVICE |
false |
- |
DEPICTIO_MONGODB_DB_NAME |
depictioDB |
- |
DEPICTIO_MONGODB_WIPE |
false |
- |
DEPICTIO_MONGODB_USERNAME |
- | Username, for operator-managed replica-set auth |
DEPICTIO_MONGODB_PASSWORD |
- | Password, for operator-managed replica-set auth |
DEPICTIO_MONGODB_REPLICA_SET |
- | Replica set name, e.g. rs0 |
DEPICTIO_MONGODB_AUTH_SOURCE |
admin |
Authentication source database |
S3 Storage¶
Config Class: S3DepictioCLIConfig
Environment Prefix: DEPICTIO_S3_ (legacy DEPICTIO_MINIO_)
S3-compatible object storage: the bundled SeaweedFS store (Compose service s3),
or any external S3 endpoint (AWS, NetApp, Ceph, MinIO, …) set with
DEPICTIO_S3_PUBLIC_URL and DEPICTIO_S3_EXTERNAL_SERVICE=true.
DEPICTIO_MINIO_* became DEPICTIO_S3_* in v1.12.0
The bundled store is SeaweedFS instead of MinIO since v1.12.0, and these
settings were renamed with it. The former DEPICTIO_MINIO_<FIELD> names still
work: each is read when its DEPICTIO_S3_<FIELD> counterpart is unset, the new
name wins when both are set, and the server logs a deprecation warning naming
the old variables it found. An install that used the bundled MinIO has to copy
its data to the new store: see
Upgrading to v1.12.0: MinIO → SeaweedFS.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_S3_SERVICE_NAME |
s3 |
Host name of the store inside the Compose network (minio before v1.12.0, still an alias of the s3 service) |
DEPICTIO_S3_SERVICE_PORT |
9000 |
- |
DEPICTIO_S3_EXTERNAL_HOST |
localhost |
- |
DEPICTIO_S3_EXTERNAL_PORT |
9000 |
- |
DEPICTIO_S3_EXTERNAL_PROTOCOL |
http |
- |
DEPICTIO_S3_PUBLIC_URL |
- | Full endpoint URL of an external S3 |
DEPICTIO_S3_EXTERNAL_SERVICE |
false |
true when the store is outside the Docker Compose network |
DEPICTIO_S3_ROOT_USER |
minio |
S3 access key |
DEPICTIO_S3_ROOT_PASSWORD |
(required, ≥8 chars) | S3 secret key. REQUIRED in server context — must not match a known-default value. |
DEPICTIO_S3_BUCKET |
depictio-bucket |
- |
DEPICTIO_S3_VERIFY_TLS |
true |
Verify TLS certificates when connecting to S3. Set to false only for local dev with self-signed certificates. |
Required S3 permissions¶
At startup the server checks that the configured bucket is usable. Since
v1.5.2 those checks are scoped to that single bucket: HeadBucket, then a
put/delete round trip on a test object.
A credential that can only reach DEPICTIO_S3_BUCKET is therefore enough,
which is useful on managed S3 where keys are issued per bucket rather than per
account.
Since v1.6.0 the server creates the bucket before running those checks, so
you do not have to provision it first: pointing a fresh deployment at empty
object storage is enough. A bucket that already exists is left alone: creation
short-circuits and no CreateBucket call is made, so a credential issued
against an existing bucket needs no extra permission.
Account-wide ListBuckets is no longer required
Before v1.5.2 the check called ListBuckets, an account-level operation.
Bucket-scoped credentials got AccessDenied and the server refused to start,
even though the bucket itself was perfectly usable.
Before v1.6.0, a first boot against empty storage failed
The checks ran before the line that creates the bucket, so a deployment with nothing provisioned ahead of it died during startup with "Bucket 'depictio-bucket' does not exist". Genuinely broken storage still refuses to start, since the checks now simply follow creation.
Remote Data Sources (v1.16.0+)¶
Config Class: RemoteConfig
Environment Prefix: DEPICTIO_REMOTE_
Policy for reading user-supplied locations: the gateway that fetches https://
URLs (the url and manifest scan modes, manifest downloads, the endpoint
gating of per-project storage credentials), and which s3:// buckets the
server may read without the project's storage settings. The section is read
from the environment on every read, so the API and the Celery worker apply the
same policy, and a malformed value fails at the first read instead of silently
falling back to a default. The run-folder browser then offers no S3 location,
and the server log says why. See
Remote data and manifests
and Security.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_REMOTE_ALLOW_HTTP |
false |
Accept plain http:// URLs in addition to https:// and s3://. Off by default: the gateway and the models reject http:// locations. Turn on for local or airgapped deployments that serve data without TLS |
DEPICTIO_REMOTE_URL_ALLOWLIST |
(empty) | Comma-separated host names the gateway may fetch from. Exclusive while set: any host not listed is rejected, and a listed host skips the private/loopback address rejection, which is how internal deployments opt an intranet host in. Empty accepts every public host |
DEPICTIO_REMOTE_URL_DENYLIST |
(empty) | Comma-separated host names the gateway always rejects. Checked before the allowlist, so a host present in both lists is denied |
DEPICTIO_REMOTE_PUBLIC_S3_BUCKETS |
(empty) | Comma-separated S3 locations read without credentials, each bucket or bucket/prefix, on Amazon S3. Unsigned access is opt-in: any other s3:// location needs the project's storage settings, read unsigned too when they hold no key, or an entry in the next list |
DEPICTIO_REMOTE_CREDENTIALED_S3_BUCKETS |
(empty) | Comma-separated S3 locations, same syntax, that the API and the worker read with their own ambient credentials (the AWS default chain: environment, IAM role, web identity). Every user of the instance can read what is listed here. Not used by the CLI |
DEPICTIO_REMOTE_MAX_DOWNLOAD_BYTES |
524288000 (500 MiB) |
Size cap in bytes for a single remote download: a data file, a manifest the CLI reads, a MultiQC report. Downloads stream and abort, removing the partial file, once the cap is exceeded. The server reads a manifest up to 50 MiB, or this cap when it is lower |
DEPICTIO_REMOTE_TIMEOUT_S |
30.0 |
Timeout in seconds applied to each connect, read and write operation of a remote fetch, not a total download time. Also the connect and read timeouts of the S3 client that reads a user-supplied s3:// location |
DEPICTIO_REMOTE_MAX_REDIRECTS |
3 |
Maximum redirect hops followed for a remote URL. Every Location is re-validated against this policy before it is followed |
A listed host bypasses the private-address check
Setting DEPICTIO_REMOTE_URL_ALLOWLIST both restricts fetches to the listed
hosts and exempts those hosts from the private-range rejection. List only
hosts you control.
The backend and the Celery worker must agree on these variables:
| Deployment | Where to set them |
|---|---|
| Kubernetes | backend.env in the Helm values, rendered for both the backend and the Celery worker |
| Docker Compose | .env, passed to both the backend and the worker |
| Python package | The shell that runs depictio local up, which passes DEPICTIO_REMOTE_* on to the server, but not AWS_*: see depictio local |
Local data folders (v1.16.0+)¶
Config Class: LocalDataConfig
Environment Prefix: DEPICTIO_LOCAL_DATA_
| Variable | Default | Description |
|---|---|---|
DEPICTIO_LOCAL_DATA_ROOTS |
(empty) | Comma-separated absolute folders (or ~/...) the web UI may read run folders from. Empty turns local folders off. Honoured only with DEPICTIO_AUTH_SINGLE_USER_MODE; hidden folders and the folders Depictio keeps for itself are never read |
depictio local up sets it to your home folder plus each
--data-root-allow folder; there is no need to set it
by hand. See From a run folder.
Authentication¶
Config Class: AuthConfig
Environment Prefix: DEPICTIO_AUTH_
Authentication and authorization settings including JWT configuration, unauthenticated mode, and Google OAuth integration.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_AUTH_KEYS_DIR |
<repo>/keys |
Directory for JWT public/private key files. Also holds secrets_key.bin, the key that encrypts per-project storage credentials at rest; the backend and the Celery worker must mount the same directory, or secrets written by one are unreadable by the other |
DEPICTIO_AUTH_KEYS_ALGORITHM |
RS256 |
JWT signing algorithm (RS256, RS512, ES256, SHA256) |
DEPICTIO_AUTH_CLI_CONFIG_DIR |
<repo>/.depictio |
Directory for CLI configuration files (admin token, etc.) |
DEPICTIO_AUTH_INTERNAL_API_KEY_ENV |
(auto-generated) | Internal API key for service-to-service communication |
DEPICTIO_AUTH_UNAUTHENTICATED_MODE |
false |
Enable unauthenticated mode |
DEPICTIO_AUTH_SINGLE_USER_MODE |
false |
Single-user mode for personal/self-hosted instances — grants admin privileges to the anonymous user |
DEPICTIO_AUTH_PUBLIC_MODE |
false |
Public mode for public instances — anonymous access with optional sign-in |
DEPICTIO_AUTH_DEMO_MODE |
false |
Demo mode — extends public mode with guided tour tooltips for first-time users |
DEPICTIO_AUTH_ANONYMOUS_USER_EMAIL |
anonymous@depict.io |
Default anonymous user email |
DEPICTIO_AUTH_TEMPORARY_USER_EXPIRY_HOURS |
24 |
Number of hours until temporary users expire |
DEPICTIO_AUTH_TEMPORARY_USER_EXPIRY_MINUTES |
0 |
Number of minutes until temporary users expire |
DEPICTIO_AUTH_GOOGLE_OAUTH_ENABLED |
false |
Enable Google OAuth authentication |
DEPICTIO_AUTH_GOOGLE_OAUTH_CLIENT_ID |
- | Google OAuth client ID |
DEPICTIO_AUTH_GOOGLE_OAUTH_CLIENT_SECRET |
- | Google OAuth client secret |
DEPICTIO_AUTH_GOOGLE_OAUTH_REDIRECT_URI |
- | Google OAuth redirect URI |
DEPICTIO_AUTH_REGISTRATION_DISABLED |
false |
Block self-service registration: /register returns 403 and the Register UI is hidden, so only pre-provisioned accounts can log in. Independent of public/single-user mode |
DEPICTIO_AUTH_PROVISIONING_API_KEY |
- | Shared secret for pipeline-side user provisioning (POST /auth/provision_user). Scoped to provisioning only, kept separate from the internal API key. Also accepted as DEPICTIO_AUTH_PROVISIONING_API_KEY_ENV. The provisioning endpoints are disabled while this is unset. See Pipeline provisioning |
DEPICTIO_AUTH_MAGIC_LINK_EXPIRY_MINUTES |
15 |
Lifetime of a single-use magic-link login ticket |
Bootstrap¶
Config Class: AuthBootstrapConfig
Environment Prefix: DEPICTIO_BOOTSTRAP_
First-boot admin seeding — replaces the legacy initial_users.yaml. Idempotent: the admin is only created when no admin exists in MongoDB, so operator-set passwords survive container restarts and Helm wipe-jobs.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_BOOTSTRAP_ADMIN_EMAIL |
(required) | Email address for the initial admin. REQUIRED when no admin exists in MongoDB. |
DEPICTIO_BOOTSTRAP_ADMIN_PASSWORD |
(required, ≥8 chars) | Password for the bootstrap admin. changeme is accepted for local dev. |
DEPICTIO_BOOTSTRAP_SEED_TEST_USER |
false |
Seed a non-admin test user for CI/Cypress fixtures. Leave false in production. |
DEPICTIO_BOOTSTRAP_TEST_USER_EMAIL |
test_user@example.com |
Email for the CI test user (only when seed_test_user=true). |
DEPICTIO_BOOTSTRAP_TEST_USER_PASSWORD |
test_pwd |
Password for the CI test user (only when seed_test_user=true). |
Redis Cache¶
Config Class: CacheConfig
Environment Prefix: DEPICTIO_CACHE_
Redis cache configuration settings.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_CACHE_REDIS_HOST |
redis |
Redis server hostname |
DEPICTIO_CACHE_REDIS_PORT |
6379 |
Redis server port |
DEPICTIO_CACHE_REDIS_PASSWORD |
- | Redis password |
DEPICTIO_CACHE_REDIS_DB |
0 |
Redis database number |
DEPICTIO_CACHE_REDIS_SSL |
false |
Use SSL for Redis connection |
DEPICTIO_CACHE_ENABLE_REDIS_CACHE |
true |
Enable Redis caching for DataFrames |
DEPICTIO_CACHE_FALLBACK_TO_MEMORY |
true |
Fallback to in-memory cache if Redis fails |
DEPICTIO_CACHE_DEFAULT_TTL |
3600 |
Default cache TTL in seconds (1 hour) |
DEPICTIO_CACHE_DATAFRAME_TTL |
1800 |
DataFrame cache TTL in seconds (30 minutes) |
DEPICTIO_CACHE_MAX_DATAFRAME_SIZE_MB |
100 |
Maximum DataFrame size to cache (MB) |
DEPICTIO_CACHE_REDIS_MAX_MEMORY_MB |
1024 |
Not enforced. Declared but never applied to the Redis server; see the note below. |
DEPICTIO_CACHE_CACHE_KEY_PREFIX |
depictio:df: |
Prefix for cache keys |
DEPICTIO_CACHE_CACHE_VERSION |
v1 |
Cache version for key namespacing |
Cap Redis on the server, not through Depictio
DEPICTIO_CACHE_REDIS_MAX_MEMORY_MB is read into settings and then never applied:
Depictio issues no CONFIG SET, so setting it leaves Redis uncapped. A cache that
grows until the container's memory limit kills it takes the Celery broker down with it
when both share one Redis, which fails every figure offload until it recovers.
Set the limit on Redis itself instead, and give it an eviction policy:
volatile-lru rather than allkeys-lru because the policy is server-wide: cache
entries are written with a TTL and broker keys are not, so only the cache is evicted.
Celery Task Queue¶
Config Class: CeleryConfig
Environment Prefix: DEPICTIO_CELERY_
Celery task queue configuration for background processing.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_CELERY_BROKER_HOST |
redis |
Redis broker hostname |
DEPICTIO_CELERY_BROKER_PORT |
6379 |
Redis broker port |
DEPICTIO_CELERY_BROKER_PASSWORD |
- | Redis broker password |
DEPICTIO_CELERY_BROKER_DB |
1 |
Redis database for Celery broker |
DEPICTIO_CELERY_RESULT_BACKEND_HOST |
redis |
Redis result backend hostname |
DEPICTIO_CELERY_RESULT_BACKEND_PORT |
6379 |
Redis result backend port |
DEPICTIO_CELERY_RESULT_BACKEND_PASSWORD |
- | Redis result backend password |
DEPICTIO_CELERY_RESULT_BACKEND_DB |
2 |
Redis database for Celery results |
DEPICTIO_CELERY_WORKER_CONCURRENCY |
2 |
Number of concurrent worker processes |
DEPICTIO_CELERY_WORKER_POOL |
threads |
Worker pool type (threads, processes) |
DEPICTIO_CELERY_WORKER_PREFETCH_MULTIPLIER |
1 |
Worker prefetch multiplier |
DEPICTIO_CELERY_WORKER_MAX_TASKS_PER_CHILD |
50 |
Max tasks per worker before restart |
DEPICTIO_CELERY_TASK_SOFT_TIME_LIMIT |
300 |
Task soft time limit in seconds (5min) |
DEPICTIO_CELERY_TASK_TIME_LIMIT |
600 |
Task hard time limit in seconds (10min) |
DEPICTIO_CELERY_RESULT_EXPIRES |
3600 |
Task result expiration in seconds (1hr) |
DEPICTIO_CELERY_DEFAULT_QUEUE |
dashboard_tasks |
Not applied: a task with no route goes to the celery queue, the one the bundled worker reads |
DEPICTIO_CELERY_INGESTION_QUEUE |
ingestion |
Queue of the offloaded ingestion tasks, read by the ingestion worker (v1.15.0+) |
DEPICTIO_CELERY_WORKER_SEND_TASK_EVENTS |
true |
Enable task event monitoring |
DEPICTIO_CELERY_TASK_SEND_SENT_EVENT |
true |
Send task sent events |
DEPICTIO_CELERY_OFFLOAD_PREVIEW |
true |
Offload component-design preview endpoints (/figure/preview, etc.) to Celery |
DEPICTIO_CELERY_OFFLOAD_RENDERING |
false |
Force-offload all dashboard render endpoints (/dashboards/render_*) to Celery. Off by default: renders offload adaptively by size instead |
DEPICTIO_CELERY_OFFLOAD_SIZE_THRESHOLD_BYTES |
52428800 (50 MB) |
Source Delta-table size at/above which a render is offloaded even when OFFLOAD_RENDERING is off. 0 disables size-based offload |
DEPICTIO_CELERY_OFFLOAD_TIMEOUT_SECONDS |
30.0 |
Per-request Celery offload timeout in seconds before HTTP 504 |
Real-time Events¶
Config Class: EventsConfig
Environment Prefix: DEPICTIO_EVENTS_
Real-time dashboard events (WebSocket live refresh). Disabled by default — set
DEPICTIO_EVENTS_ENABLED=true to turn the system on. Uses Redis pub/sub to fan events out to
connected viewers, so a reachable Redis instance is required when enabled. See
Real-time Events for the full setup.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_EVENTS_ENABLED |
false |
Master switch for the real-time event system |
DEPICTIO_EVENTS_REDIS_HOST |
redis |
Redis hostname for pub/sub |
DEPICTIO_EVENTS_REDIS_PORT |
6379 |
Redis port |
DEPICTIO_EVENTS_REDIS_PASSWORD |
- | Redis password (optional) |
DEPICTIO_EVENTS_REDIS_DB |
3 |
Redis database number (cache=0, celery=1,2) |
DEPICTIO_EVENTS_MONGODB_CHANGE_STREAMS_ENABLED |
true |
Enable MongoDB change streams for data collections (requires a replica set) |
DEPICTIO_EVENTS_WS_HEARTBEAT_INTERVAL |
30 |
WebSocket heartbeat/ping interval in seconds |
DEPICTIO_EVENTS_WS_CONNECTION_TIMEOUT |
60 |
WebSocket connection timeout in seconds |
DEPICTIO_EVENTS_DEBOUNCE_MS |
1000 |
Debounce interval in milliseconds for rapid updates |
Dev-only trigger endpoint
DEPICTIO_ENABLE_DEV_ENDPOINTS (default false, prefix DEPICTIO_) gates the
admin-only /events/test-trigger/{dc_id} route used to broadcast a test event by hand. It is
not required for normal event-driven refresh — data ingestion drives that on its own.
Performance & Timeouts¶
Config Class: PerformanceConfig
Environment Prefix: DEPICTIO_PERFORMANCE_
Performance and timeout settings that can be tuned per environment.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_PERFORMANCE_HTTP_CLIENT_TIMEOUT |
30 |
- |
DEPICTIO_PERFORMANCE_API_REQUEST_TIMEOUT |
60 |
- |
DEPICTIO_PERFORMANCE_BROWSER_NAVIGATION_TIMEOUT |
60000 |
- |
DEPICTIO_PERFORMANCE_BROWSER_PAGE_LOAD_TIMEOUT |
90000 |
- |
DEPICTIO_PERFORMANCE_BROWSER_ELEMENT_TIMEOUT |
30000 |
- |
DEPICTIO_PERFORMANCE_SCREENSHOTS_ENABLED |
true |
Generate dashboard thumbnails with Playwright. depictio local up sets it to false unless --screenshots is passed |
DEPICTIO_PERFORMANCE_SCREENSHOTS_DIR |
package's api/static/screenshots |
Where thumbnails are written and served from. At startup, thumbnails of dashboards absent from the database are deleted from it |
DEPICTIO_PERFORMANCE_SCREENSHOT_NAVIGATION_TIMEOUT |
45000 |
- |
DEPICTIO_PERFORMANCE_SCREENSHOT_CONTENT_WAIT |
15000 |
- |
DEPICTIO_PERFORMANCE_SCREENSHOT_STABILIZATION_WAIT |
5000 |
- |
DEPICTIO_PERFORMANCE_SCREENSHOT_CAPTURE_TIMEOUT |
90000 |
- |
DEPICTIO_PERFORMANCE_SCREENSHOT_API_TIMEOUT |
300 |
- |
DEPICTIO_PERFORMANCE_SCREENSHOT_VIEWPORT_WIDTH |
1440 |
Width of the page a dashboard thumbnail is captured from, in CSS pixels (v1.11.2+) |
DEPICTIO_PERFORMANCE_SCREENSHOT_VIEWPORT_HEIGHT |
900 |
Height of that page, in CSS pixels (v1.11.2+) |
DEPICTIO_PERFORMANCE_SCREENSHOT_SCALE |
2.0 |
Pixel density of the capture, from 1.0 to 3.0. Each capture also writes an @2x file for the hover preview (v1.11.2+) |
DEPICTIO_PERFORMANCE_SERVICE_READINESS_RETRIES |
5 |
- |
DEPICTIO_PERFORMANCE_SERVICE_READINESS_DELAY |
3 |
- |
DEPICTIO_PERFORMANCE_SERVICE_READINESS_TIMEOUT |
10 |
- |
DEPICTIO_PERFORMANCE_DNS_CACHE_TTL |
300 |
- |
DEPICTIO_PERFORMANCE_CONNECTION_POOL_SIZE |
10 |
- |
DEPICTIO_PERFORMANCE_MAX_KEEPALIVE_CONNECTIONS |
5 |
- |
DEPICTIO_PERFORMANCE_DISABLE_LOADING_SPINNERS |
true |
Disable all loading spinners for maximum performance |
DEPICTIO_PERFORMANCE_DISABLE_ANIMATIONS |
true |
Disable SVG and CSS animations for maximum performance |
DEPICTIO_PERFORMANCE_DISABLE_THEME_ANIMATIONS |
true |
Disable theme CSS injection and complex theme operations |
Render caps¶
Bound how many rows a single figure, table or advanced-viz render materialises, so large data collections stay responsive. See Performance & Scaling for what each cap does to the rendered result.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_PERFORMANCE_FIGURE_MAX_POINTS |
10000 |
Target marker count for point plots (scatter family). Above it the figure is downsampled before serialising to Plotly. A per-component max_points overrides this |
DEPICTIO_PERFORMANCE_FIGURE_MAX_LOAD_ROWS |
500000 |
Row ceiling loaded from Delta for a point-plot / code-mode figure. Bypassed when the client requests a full load |
DEPICTIO_PERFORMANCE_TABLE_SORT_MAX_ROWS |
1000000 |
Post-filter row count above which a table is served in natural scan order instead of sorted; the response reports sort_disabled so the grid drops the sort affordance. 0 disables the gate |
DEPICTIO_PERFORMANCE_ADVANCED_VIZ_NO_SAMPLE_MAX_ROWS |
2000000 |
Row ceiling for the advanced-viz kinds that must not be sampled. Past it the request falls back to a uniform sample and the chart is marked estimated. 0 disables the ceiling |
DEPICTIO_PERFORMANCE_ADVANCED_VIZ_TAIL_P_THRESHOLD |
0.05 |
Significance cutoff below which a volcano/Manhattan row is kept whole rather than sampled. Fallback only, since a renderer's own threshold wins |
DEPICTIO_PERFORMANCE_ADVANCED_VIZ_TAIL_EFFECT_THRESHOLD |
1.0 |
Same, for kinds whose tail is a signed effect size (MA's log2 fold change) |
DEPICTIO_PERFORMANCE_BOX_SAMPLE_ROWS_PER_GROUP |
0 |
Rows sampled per box-plot group before computing quartiles; 0 computes them exactly. Trades a sort for an extra scan, so see the tuning notes |
DEPICTIO_PERFORMANCE_BOX_SAMPLE_MAX_GROUPS |
64 |
Group-count ceiling above which box quartiles are always computed exactly (grouped quantiles get cheaper as cardinality rises) |
Backup & Restore¶
Config Class: BackupConfig
Environment Prefix: DEPICTIO_BACKUP_
Backup and restore configuration settings.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_BACKUP_BASE_DIR |
PydanticUndefined |
- |
DEPICTIO_BACKUP_BACKUP_DIR |
backups |
- |
DEPICTIO_BACKUP_S3_BACKUP_STRATEGY |
s3_to_s3 |
Strategy for S3 data backup: 's3_to_s3', 'local', or 'both' |
DEPICTIO_BACKUP_S3_LOCAL_BACKUP_DIR |
backups/s3_data_backups |
- |
DEPICTIO_BACKUP_BACKUP_S3_ENABLED |
false |
Enable separate backup S3 bucket |
DEPICTIO_BACKUP_BACKUP_S3_BUCKET |
depictio-backups |
Backup S3 bucket name |
DEPICTIO_BACKUP_BACKUP_S3_ENDPOINT_URL |
- | Backup S3 endpoint URL |
DEPICTIO_BACKUP_BACKUP_S3_ACCESS_KEY |
- | Backup S3 access key |
DEPICTIO_BACKUP_BACKUP_S3_SECRET_KEY |
- | Backup S3 secret key |
DEPICTIO_BACKUP_BACKUP_S3_REGION |
us-east-1 |
Backup S3 region |
DEPICTIO_BACKUP_COMPRESS_LOCAL_BACKUPS |
true |
Compress local S3 data backups |
DEPICTIO_BACKUP_BACKUP_FILE_RETENTION_DAYS |
30 |
Days to retain backup files |
DEPICTIO_BACKUP_MIGRATION_ALLOWED_S3_ENDPOINTS |
(empty) | Comma-separated allowlist of external S3 endpoints permitted for project migration. Empty = only the deployment's own S3 store is allowed (SSRF guard). |
Google Analytics¶
Config Class: GoogleAnalyticsConfig
Environment Prefix: DEPICTIO_GOOGLE_ANALYTICS_
Configuration for Google Analytics tracking.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_GOOGLE_ANALYTICS_ENABLED |
false |
Enable Google Analytics tracking |
DEPICTIO_GOOGLE_ANALYTICS_TRACKING_ID |
- | Google Analytics tracking ID (GA4 measurement ID) |
Logging¶
Config Class: LoggingConfig
Environment Prefix: DEPICTIO_LOGGING_
Logging verbosity and output configuration.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_LOGGING_VERBOSITY_LEVEL |
ERROR |
- |
S3 File Cache¶
Config Class: S3CacheConfig
Environment Prefix: DEPICTIO_S3_
S3 file caching configuration for MultiQC and other S3 operations.
The cache directory stores downloaded S3 files locally to avoid repeated downloads. Default location is ~/.depictio/s3_cache (persistent across restarts).
Environment variable: DEPICTIO_S3_CACHE_DIR Example: export DEPICTIO_S3_CACHE_DIR=/data/depictio_s3_cache
Note: The previous default /tmp/depictio_s3_cache was ephemeral and caused repeated downloads after system restarts.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_S3_CACHE_DIR |
~/.depictio/s3_cache |
Local directory for S3 file cache. Use DEPICTIO_S3_CACHE_DIR to override. |
Monitoring¶
Config Class: MonitoringConfig
Environment Prefix: DEPICTIO_MONITORING_
Feeds the admin Log & Task panel. See Monitoring.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_MONITORING_ENABLED |
true |
Enable the admin monitoring feature |
DEPICTIO_MONITORING_RETENTION_DAYS |
14 |
TTL in days for task_events records before automatic expiry |
DEPICTIO_MONITORING_APP_LOG_MIN_LEVEL |
WARNING |
Minimum level captured into app_logs. One of DEBUG, INFO, WARNING, ERROR, CRITICAL |
DEPICTIO_MONITORING_APP_LOG_CAPPED_MB |
64 |
Size cap in MB of the capped app_logs collection |
DEPICTIO_MONITORING_LIVE_UPDATES |
true |
Push live task and ingestion status over the events WebSocket. Only active when DEPICTIO_EVENTS_ENABLED is also true |
DEPICTIO_MONITORING_INGESTION_STALE_AFTER_HOURS |
24 |
Hours without a write after which a running ingestion is swept to abandoned. 0 disables the sweep. The bundled compose files and Helm chart do not forward it, so set it on the backend yourself (v1.11.0+) |
DEPICTIO_MONITORING_AGENT_TTL_SECONDS |
300 |
How long a watcher stays listed after its last heartbeat. At least 60 |
Dashboard Versions¶
Config Class: DashboardVersionsConfig
Environment Prefix: DEPICTIO_DASHBOARD_VERSIONS_
The version history of every dashboard. See Dashboard and data versions.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_DASHBOARD_VERSIONS_ENABLED |
true |
Record a version on each dashboard save. Off, nothing new is recorded |
DEPICTIO_DASHBOARD_VERSIONS_COALESCE_WINDOW_SECONDS |
300 |
How long consecutive autosaves by the same author fold into one version, counted from its creation |
DEPICTIO_DASHBOARD_VERSIONS_MAX_VERSIONS_PER_FAMILY |
100 |
Autosaves kept per dashboard, bookmarked ones aside |
DEPICTIO_DASHBOARD_VERSIONS_RETENTION_DAYS |
90 |
Age after which versions that are not bookmarked are dropped |
DEPICTIO_DASHBOARD_VERSIONS_KEEP_DAILY_FOR_DAYS |
30 |
Age after which autosaves thin to the last one of each day |
DEPICTIO_DASHBOARD_VERSIONS_MAX_SNAPSHOT_BYTES |
8388608 (8 MiB) |
Largest version recorded. A larger one is skipped and logged; the save itself goes through |
Ingestion¶
Config Class: IngestionConfig
Environment Prefix: DEPICTIO_INGESTION_
Server-side limits and opt-ins for ingestion (v1.15.0+). Everything but the step limit is off by default. See Ingestion worker.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_INGESTION_STEP_UPDATES_PER_MINUTE |
60 |
Live step updates recorded per ingestion run and minute. success, failed and skipped steps always pass. See Monitoring |
DEPICTIO_INGESTION_ASYNC_DELTATABLE_UPSERT |
false |
Hand the profiling of a written table to the ingestion worker when the CLI asks with --async-upsert. Needs DEPICTIO_JOBS_ENABLED, without which it stays inline. See Offloading the table profile |
DEPICTIO_INGESTION_BROWSER_TRIGGER |
false |
Offer Run ingestion on project pages to owners, editors and admins. Needs DEPICTIO_JOBS_ENABLED and DEPICTIO_INGESTION_ALLOWED_DATA_ROOTS. See Starting an ingestion from the browser |
DEPICTIO_INGESTION_ALLOWED_DATA_ROOTS |
empty | Directories a browser-started ingestion may read, comma-separated or as a JSON list. Every path a project names, and every file its scan registers, must resolve inside one of them. Empty refuses every ingestion |
Jobs¶
Config Class: JobsConfig
Environment Prefix: DEPICTIO_JOBS_
Records of work the server accepted but finishes in the background, polled through the /jobs API (v1.15.0+). Off by default.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_JOBS_ENABLED |
false |
Create the jobs collection and serve /jobs. Required by both offloaded ingestion features |
DEPICTIO_JOBS_RETENTION_HOURS |
24 |
How long a successful job is kept |
DEPICTIO_JOBS_FAILED_RETENTION_HOURS |
168 |
How long a failed or cancelled job is kept |
DEPICTIO_JOBS_MAX_RESULT_BYTES |
262144 |
Largest job result stored. A larger one is dropped and the job marked result_truncated |
Telemetry¶
Config Class: TelemetryConfig
Environment Prefix: DEPICTIO_TELEMETRY_
Anonymous installation heartbeat. See Telemetry for what is sent and how to inspect it.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_TELEMETRY_ENABLED |
true |
Send anonymous installation telemetry. Also suppressed by DO_NOT_TRACK, in CI, under pytest, and when DEPICTIO_MONGODB_WIPE is set |
DEPICTIO_TELEMETRY_ENDPOINT |
PostHog Cloud EU | Collector ingestion URL, PostHog-compatible capture endpoint |
DEPICTIO_TELEMETRY_API_KEY |
Depictio's own project | Collector project token. Public write-only key, carries no read access. Override only to point at your own collector |
DEPICTIO_TELEMETRY_INTERVAL_HOURS |
24 |
Hours between heartbeat attempts, 1–168. At most one send per UTC day either way |
DEPICTIO_TELEMETRY_DEPLOYMENT_KIND |
auto-detected | Override the detected kind: helm, kubernetes, docker-compose, docker-compose-dev, docker, devcontainer, local |
DEPICTIO_TELEMETRY_INCLUDE_USAGE_METRICS |
true |
Include bucketed deployment-size counts. Disable to send only install identity and version |
DEPICTIO_TELEMETRY_DEBUG |
false |
Log the payload instead of sending it, so an operator can audit telemetry before deciding |
DEPICTIO_TELEMETRY_STATE_DIR |
~/.depictio |
Where the CLI stores its anonymous ID |
Five more are stated by the Helm chart from its own values.yaml and are unset
outside Helm: DEPICTIO_TELEMETRY_REPLICAS, DEPICTIO_TELEMETRY_CPU_REQUEST,
DEPICTIO_TELEMETRY_CPU_LIMIT, DEPICTIO_TELEMETRY_MEMORY_REQUEST and
DEPICTIO_TELEMETRY_MEMORY_LIMIT. CPU quantities are parsed to millicores and
memory to MiB before they can reach the payload; neither is ever sent raw.
MultiQC Prerender¶
Config Class: MultiQCPrerenderConfig
Environment Prefix: DEPICTIO_MULTIQC_
| Variable | Default | Description |
|---|---|---|
DEPICTIO_MULTIQC_PRERENDER_DIR |
~/.depictio/multiqc_prerender |
Local directory for pre-rendered MultiQC figures |
Global Settings¶
Config Class: Settings
Environment Prefix: DEPICTIO_
Top-level application settings including context configuration.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_CONTEXT |
server |
- |
DEPICTIO_DISABLE_EXAMPLE_DASHBOARDS |
false |
Skip seeding the bundled reference projects (Iris, Penguins, Advanced Visualisations, nf-core/ampliseq, nf-core/viralrecon) and their dashboards on API startup. Opt-in: default preserves current behaviour. |
DEPICTIO_SEED_PROJECTS |
(empty = all) | Comma-separated allowlist of bundled reference datasets to seed on startup (e.g. iris or iris,penguins). Empty seeds all of them. Ignored when DEPICTIO_DISABLE_EXAMPLE_DASHBOARDS=true (that takes precedence and seeds none). Used by the devcontainer/Codespaces setup to seed only iris for a faster boot. |
DEPICTIO_WALKTHROUGH_DISABLED |
false |
Hide the onboarding walkthrough overlay for every user. Useful for embedded iframes, staging envs used for screenshot capture, and demos with their own narration. DEPICTIO_DEV_MODE=true also suppresses it. |
Branding¶
Config Class: BrandingSettings
Environment Prefix: DEPICTIO_BRANDING_
Deployment-level defaults for the brand theme. Every one of these is the leftmost layer: the /admin Branding panel and a dashboard's own override sit on top of them, and neither needs a redeploy. Leave a variable unset and the layer above, or Depictio's own look, applies.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_BRANDING_PRESET |
- | Starting point seeded into the theme: depictio, trec, embl or ocean. The flat variables below override it field by field. |
DEPICTIO_BRANDING_APP_NAME |
Depictio |
Browser tab title and login greeting |
DEPICTIO_BRANDING_LOGO_URL |
- | Logo for light mode. Absolute (https://) or a path this deployment serves |
DEPICTIO_BRANDING_LOGO_URL_DARK |
- | Logo for dark mode. Falls back to DEPICTIO_BRANDING_LOGO_URL |
DEPICTIO_BRANDING_PRIMARY_COLOR |
- | Primary brand colour. Hex, or a Mantine palette name (blue, teal, grape, ...). A hex value is expanded server-side into a 10-shade tuple with your colour on the shade a filled button paints |
DEPICTIO_BRANDING_SECONDARY_COLOR |
- | Secondary brand colour |
DEPICTIO_BRANDING_TERTIARY_COLOR |
- | Tertiary / accent brand colour |
DEPICTIO_BRANDING_TINT_MODE |
accent |
How far the brand reaches. accent re-tints the primary accent only; full also gives the secondary and tertiary the app's existing teal and orange accent families. gray, red, green and yellow are never remapped |
DEPICTIO_BRANDING_SUCCESS_COLOR |
- | Overrides Mantine green. Status colours stay outside the brand reach so pass / warn / fail keep reading as meaning |
DEPICTIO_BRANDING_WARNING_COLOR |
- | Overrides Mantine yellow |
DEPICTIO_BRANDING_DANGER_COLOR |
- | Overrides Mantine red |
DEPICTIO_BRANDING_FONT_FAMILY |
- | Body font stack. Must be installed or served by this deployment; none is fetched for you |
DEPICTIO_BRANDING_HEADINGS_FONT_FAMILY |
- | Headings font stack |
DEPICTIO_BRANDING_DEFAULT_RADIUS |
- | Corner radius as a Mantine token, xs to xl |
DEPICTIO_BRANDING_COLORWAY |
(derived) | Categorical figure palette, comma-separated hex. Derived from the brand palette when unset |
DEPICTIO_BRANDING_SEQUENTIAL |
(derived) | Continuous figure scale, comma-separated hex. Derived from the brand palette when unset |
DEPICTIO_BRANDING_PLOT_TEMPLATE |
- | Plotly template for figures whose component picks none. Unset means follow the UI colour scheme, using Depictio's brand-aware mantine_light / mantine_dark |
DEPICTIO_BRANDING_THEME |
- | Escape hatch: a whole brand theme as JSON, for fields with no flat variable of their own (the per-scheme chrome surfaces). Merged under the flat variables above |
Full commented block
The depictio repository ships the whole set with inline commentary in .env.example, and a Kubernetes equivalent in helm-charts/depictio/examples/values-branding.yaml.
Chrome surfaces need the JSON variable
app_bg, section_bg, nav_bg and heading are set per colour scheme, so they have no flat variable. Pass them through DEPICTIO_BRANDING_THEME:
Release Check (v1.17.0+)¶
Config Class: VersionCheckConfig
Environment Prefix: DEPICTIO_VERSION_CHECK_
Tells administrators when a newer Depictio release is published. The API asks the GitHub Releases API with an unauthenticated GET that sends nothing about the instance. See Release check.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_VERSION_CHECK_ENABLED |
(unset) | Unset: the check is on and administrators can turn it off in Administration → Settings. true or false decides instead and locks that switch |
DEPICTIO_VERSION_CHECK_INTERVAL_HOURS |
6 |
Hours between checks, 1 to 168, once for the whole instance |
DEPICTIO_VERSION_CHECK_REPOSITORY |
depictio/depictio |
GitHub repository whose releases are compared with the running version |
DEPICTIO_VERSION_CHECK_TIMEOUT_SECONDS |
10 |
Timeout of the GitHub request |
Feedback¶
Config Class: FeedbackConfig
Environment Prefix: DEPICTIO_FEEDBACK_
An opt-in link on every dashboard that carries the reader's context to wherever you point it: an issue form, a helpdesk, a mailto:. It renders only when enabled and a URL is set (v1.11.0+).
| Variable | Default | Description |
|---|---|---|
DEPICTIO_FEEDBACK_ENABLED |
false |
Show the link: an icon at the end of the dashboard header, and a Feedback section in the dashboard's Settings |
DEPICTIO_FEEDBACK_URL |
- | Link target. {dashboard}, {dashboard_id}, {tab} (the tab label the reader sees) and {url} are filled in and URL-encoded in the browser; no other placeholder is |
DEPICTIO_FEEDBACK_LABEL |
Feedback |
Icon tooltip and settings label |
DEPICTIO_FEEDBACK_ENABLED=true
DEPICTIO_FEEDBACK_URL='https://github.com/<org>/<repo>/issues/new?template=dashboard_feedback.yml&dashboard={dashboard}&tab={tab}&page={url}'
DEPICTIO_FEEDBACK_LABEL='Send feedback'
ServiceConfig¶
Config Class: ServiceConfig
Environment Prefix: DEPICTIO_
Base class for service configurations with internal/external URL handling.
| Variable | Default | Description |
|---|---|---|
DEPICTIO_SERVICE_NAME |
PydanticUndefined |
- |
DEPICTIO_SERVICE_PORT |
PydanticUndefined |
- |
DEPICTIO_EXTERNAL_HOST |
localhost |
- |
DEPICTIO_EXTERNAL_PORT |
PydanticUndefined |
- |
DEPICTIO_EXTERNAL_PROTOCOL |
http |
- |
DEPICTIO_PUBLIC_URL |
- | - |
DEPICTIO_EXTERNAL_SERVICE |
false |
- |