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_MINIO_ROOT_USER=minio
DEPICTIO_MINIO_ROOT_PASSWORD=minio123

Complete Environment File

For a ready-to-use file with all variables, copy .env.complete.example to .env and uncomment the variables you need.

Google Analytics
Logging

S3 File Cache

Global Settings
ServiceConfig

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`	-

Dash Frontend¶

Config Class: DashConfig Environment Prefix: DEPICTIO_DASH_

Base class for service configurations with internal/external URL handling.

Variable	Default	Description
`DEPICTIO_DASH_SERVICE_NAME`	`depictio-frontend`	-
`DEPICTIO_DASH_SERVICE_PORT`	`5080`	-
`DEPICTIO_DASH_EXTERNAL_HOST`	`localhost`	-
`DEPICTIO_DASH_EXTERNAL_PORT`	`5080`	-
`DEPICTIO_DASH_EXTERNAL_PROTOCOL`	`http`	-
`DEPICTIO_DASH_PUBLIC_URL`	-	-
`DEPICTIO_DASH_EXTERNAL_SERVICE`	`false`	-
`DEPICTIO_DASH_HOST`	`0.0.0.0`	-
`DEPICTIO_DASH_WORKERS`	`4`	-
`DEPICTIO_DASH_DEBUG`	`true`	-
`DEPICTIO_DASH_AUTO_GENERATE_FIGURES`	`false`	Enable automatic figure generation in UI mode

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`	-

MinIO/S3 Storage¶

Config Class: S3DepictioCLIConfig Environment Prefix: DEPICTIO_MINIO_

S3 configuration inheriting service URL management.

Variable	Default	Description
`DEPICTIO_MINIO_SERVICE_NAME`	`minio`	-
`DEPICTIO_MINIO_SERVICE_PORT`	`9000`	-
`DEPICTIO_MINIO_EXTERNAL_HOST`	`localhost`	-
`DEPICTIO_MINIO_EXTERNAL_PORT`	`9000`	-
`DEPICTIO_MINIO_EXTERNAL_PROTOCOL`	`http`	-
`DEPICTIO_MINIO_PUBLIC_URL`	-	-
`DEPICTIO_MINIO_EXTERNAL_SERVICE`	`false`	-
`DEPICTIO_MINIO_ROOT_USER`	`minio`	-
`DEPICTIO_MINIO_ROOT_PASSWORD`	`minio123`	-
`DEPICTIO_MINIO_BUCKET`	`depictio-bucket`	-

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`	`PydanticUndefined`	-
`DEPICTIO_AUTH_KEYS_ALGORITHM`	`RS256`	-
`DEPICTIO_AUTH_CLI_CONFIG_DIR`	`PydanticUndefined`	-
`DEPICTIO_AUTH_INTERNAL_API_KEY_ENV`	-	-
`DEPICTIO_AUTH_UNAUTHENTICATED_MODE`	`false`	Enable unauthenticated mode
`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

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`	Redis max memory limit (MB)
`DEPICTIO_CACHE_CACHE_KEY_PREFIX`	`depictio:df:`	Prefix for cache keys
`DEPICTIO_CACHE_CACHE_VERSION`	`v1`	Cache version for key namespacing

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`	Default task queue name
`DEPICTIO_CELERY_WORKER_SEND_TASK_EVENTS`	`true`	Enable task event monitoring
`DEPICTIO_CELERY_TASK_SEND_SENT_EVENT`	`true`	Send task sent events

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_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_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

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

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.
`DEPICTIO_S3_MOUNT_POINTS`	`""`	Comma-separated S3 FUSE mount points

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_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.

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`	-

Environment Variables Reference¶

Quick Start¶

Variable Reference by Category¶

Quick Navigation¶

FastAPI Backend¶

Dash Frontend¶

MongoDB Database¶

MinIO/S3 Storage¶

Authentication¶

Redis Cache¶

Celery Task Queue¶

Performance & Timeouts¶

Backup & Restore¶

Google Analytics¶

Logging¶

S3 File Cache¶

Global Settings¶

ServiceConfig¶

See Also¶