Environment Variables

Safebucket uses environment variables for configuration. This page documents all available environment variables organized by category.

Configuration Methods

Safebucket supports multiple configuration methods in order of precedence:

1. Environment Variables (highest precedence)
2. Configuration File (YAML format)
3. Default Values (lowest precedence)

Configuration File Path

Set the configuration file location:

CONFIG_FILE_PATH=/path/to/config.yaml

Default search paths:

• ./config.yaml
• templates/config.yaml

Environment Variable Naming Convention

Safebucket uses double underscores (__) as separators in environment variables, which map to nested configuration:

• APP__LOG_LEVEL becomes app.log_level in the config structure
• STORAGE__RUSTFS__BUCKET_NAME becomes storage.rustfs.bucket_name

This hierarchical approach makes configuration organization clear and consistent.

Application Settings

Basic Application Configuration

Variable	Description	Default	Required	Valid Values
APP__LOG_LEVEL	Logging level for the application	info	❌	debug, info, warn, error, fatal, panic
APP__PROFILE	Application profile controlling which components run	default	❌	default, api, worker
APP__API_URL	API base URL	-	✅	-
APP__WEB_URL	Frontend web URL	-	✅	-
APP__PORT	Server port (80-65535)	8080	❌	80-65535
APP__TOKEN_SECRET	Token signing secret	-	✅	-
APP__ADMIN_EMAIL	Admin user email	-	✅	Valid email
APP__ADMIN_PASSWORD	Admin user password	-	✅	-
APP__TRASH_RETENTION_DAYS	Days to retain files in trash before automatic deletion	7	❌	1-365
APP__MAX_UPLOAD_SIZE	Maximum file upload size in bytes	53687091200 (50 GB)	❌	≥ 1
APP__AUTHENTICATED_REQUESTS_PER_MINUTE	Rate limit for authenticated requests (per user)	200	❌	≥ 1
APP__UNAUTHENTICATED_REQUESTS_PER_MINUTE	Rate limit for unauthenticated requests (per IP)	20	❌	≥ 1

Profile

The APP__PROFILE setting controls which components are started:

Profile	HTTP Server	Workers
default	✅	All workers enabled
api	✅	All workers disabled
worker	❌	All workers enabled (singleton mode)

Workers are background processes that handle asynchronous tasks independently of the HTTP server: processing object deletions, handling bucket events, cleaning up trash, and running garbage collection (stale uploads, expired files/shares/sessions).

Use api and worker profiles to run the HTTP server and background workers as separate processes (e.g., in a horizontally scaled deployment).

MFA Configuration

For MFA environment variables and setup, see the MFA Configuration page.

CORS and Security

Variable	Description	Default	Required
APP__ALLOWED_ORIGINS	Comma-separated allowed origins	-	✅
APP__TRUSTED_PROXIES	Comma-separated trusted proxy IPs (CIDR notation, e.g. 10.0.0.0/8)	-	✅
APP__COOKIE_SECURE_FORCE	Force the Secure flag on auth cookies even when served over HTTP	false	❌

Example:

APP__API_URL=http://localhost:1323
APP__WEB_URL=http://localhost:3001
APP__PORT=1323
APP__TOKEN_SECRET=your-256-bit-secret
[email protected]
APP__ADMIN_PASSWORD=ChangeMePlease
APP__ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
APP__TRUSTED_PROXIES=127.0.0.1,::1

Static Files

Variable	Description	Default	Required
APP__STATIC_FILES__ENABLED	Enable static file serving	true	❌
APP__STATIC_FILES__DIRECTORY	Static files directory	web/dist	❌

TLS

Safebucket supports optional TLS termination. Providing a certificate and a key file.

Variable	Description	Default	Required
APP__TLS_CERT_FILE	Path to TLS certificate file	-	❌ (Required with key)
APP__TLS_KEY_FILE	Path to TLS private key file	-	❌ (Required with cert)

Environment variables:

APP__TLS_CERT_FILE=/etc/safebucket/tls/tls.crt
APP__TLS_KEY_FILE=/etc/safebucket/tls/tls.key

YAML configuration:

app:
  tls_cert_file: /etc/safebucket/tls/tls.crt
  tls_key_file: /etc/safebucket/tls/tls.key

tip

In containerized environments, you can mount TLS certificates as secrets and point these variables to the mount paths.

Database Configuration

Variable	Description	Default	Required
DATABASE__TYPE	Database type	postgres	❌

For detailed database configuration (PostgreSQL, SQLite), see the Database Providers page.

Authentication Configuration

For detailed authentication configuration including OIDC providers, LDAP, and domain restrictions, see the Authentication Configuration page.

Storage Configuration

Variable	Description	Default	Required
STORAGE__TYPE	Storage provider type (rustfs, minio, aws, gcp, s3)	-	✅

For detailed storage provider configuration, see the Storage Providers page.

Cache Configuration

Variable	Description	Default	Required
CACHE__TYPE	Cache provider type (memory, redis, valkey)	-	✅

For detailed cache provider configuration, see the Cache Providers page.

Events Configuration

Variable	Description	Default	Required
EVENTS__TYPE	Event provider type (jetstream, gcp, aws, memory)	-	✅

For detailed event provider configuration, see the Event Providers page.

Notification Configuration

Variable	Description	Default	Required
NOTIFIER__TYPE	Notification provider type (smtp, filesystem)	-	✅

For detailed notification provider configuration, see the Notification Providers page.

Activity Logging

Variable	Description	Default	Required
ACTIVITY__TYPE	Activity provider type (filesystem, loki)	-	✅

For detailed activity provider configuration, see the Activity Providers page.

Tracing

Safebucket can export OpenTelemetry traces to a Tempo backend. Tracing is disabled by default.

Variable	Description	Default	Required
TRACING__ENABLED	Enable distributed tracing	false	❌
TRACING__TYPE	Tracing backend (tempo)	-	❌
TRACING__TEMPO__ENDPOINT	OTLP HTTP endpoint of the collector	-	❌
TRACING__TEMPO__SERVICE_NAME	Service name reported in traces	safebucket	❌
TRACING__TEMPO__SAMPLING_RATE	Sampling rate between 0 and 1	1.0	❌

tracing:
  enabled: true
  type: tempo
  tempo:
    endpoint: http://localhost:4318
    service_name: safebucket
    sampling_rate: 1.0

Profiling

Safebucket can send continuous profiling data to a Pyroscope server. Profiling is disabled by default.

Variable	Description	Default	Required
PROFILING__ENABLED	Enable continuous profiling	false	❌
PROFILING__TYPE	Profiling backend (pyroscope)	-	❌
PROFILING__PYROSCOPE__SERVER_ADDRESS	Pyroscope server URL	-	❌
PROFILING__PYROSCOPE__APPLICATION_NAME	Application name in Pyroscope	safebucket	❌
PROFILING__PYROSCOPE__UPLOAD_RATE	Upload interval in seconds	15	❌

profiling:
  enabled: true
  type: pyroscope
  pyroscope:
    server_address: http://localhost:4040
    application_name: safebucket
    upload_rate: 15

Complete Example

Here's a complete example of environment variables for a local development setup:

# Application
APP__LOG_LEVEL=info
APP__API_URL=http://localhost:8080
APP__WEB_URL=http://localhost:8080
APP__PORT=8080
APP__TOKEN_SECRET=6n5o+dFncio8gQA4jt7pUJrJz92WrqD25zXAa8ashxA
[email protected]
APP__ADMIN_PASSWORD=ChangeMePlease
APP__ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080
APP__TRUSTED_PROXIES=127.0.0.1,::1
APP__TRASH_RETENTION_DAYS=7
APP__STATIC_FILES__ENABLED=true
APP__STATIC_FILES__DIRECTORY=web/dist

# Database
DATABASE__TYPE=postgres
DATABASE__POSTGRES__HOST=localhost
DATABASE__POSTGRES__PORT=5432
DATABASE__POSTGRES__USER=safebucket-user
DATABASE__POSTGRES__PASSWORD=safebucket-password
DATABASE__POSTGRES__NAME=safebucket
DATABASE__POSTGRES__SSLMODE=disable

# Cache (Valkey)
CACHE__TYPE=valkey
CACHE__VALKEY__HOSTS=localhost:6379
CACHE__VALKEY__PASSWORD=safebucket-password

# Storage (RustFS)
STORAGE__TYPE=rustfs
STORAGE__RUSTFS__BUCKET_NAME=safebucket
STORAGE__RUSTFS__ENDPOINT=bucket:9000
STORAGE__RUSTFS__EXTERNAL_ENDPOINT=http://localhost:9000
STORAGE__RUSTFS__ACCESS_KEY=rustfsadmin
STORAGE__RUSTFS__SECRET_KEY=rustfsadmin

# Events (NATS JetStream)
EVENTS__TYPE=jetstream
EVENTS__JETSTREAM__HOST=nats
EVENTS__JETSTREAM__PORT=4222
EVENTS__QUEUES__NOTIFICATIONS__NAME=safebucket-notifications
EVENTS__QUEUES__BUCKET_EVENTS__NAME=safebucket-bucket-events
EVENTS__QUEUES__OBJECT_DELETION__NAME=safebucket-object-deletion

# Email (SMTP)
NOTIFIER__TYPE=smtp
NOTIFIER__SMTP__HOST=mailpit
NOTIFIER__SMTP__PORT=1025
[email protected]
NOTIFIER__SMTP__TLS_MODE=none
NOTIFIER__SMTP__SKIP_VERIFY_TLS=false

# Activity Logging (Loki)
ACTIVITY__TYPE=loki
ACTIVITY__LOKI__ENDPOINT=http://loki:3100

# Authentication - Local Provider
AUTH__PROVIDERS__KEYS=local
AUTH__PROVIDERS__LOCAL__NAME=local
AUTH__PROVIDERS__LOCAL__TYPE=local

# Authentication - OIDC Provider (Optional, commented example)
# AUTH__PROVIDERS__KEYS=local,authelia
# AUTH__PROVIDERS__AUTHELIA__NAME=Authelia
# AUTH__PROVIDERS__AUTHELIA__TYPE=oidc
# AUTH__PROVIDERS__AUTHELIA__OIDC__CLIENT_ID=your-client-id
# AUTH__PROVIDERS__AUTHELIA__OIDC__CLIENT_SECRET=your-client-secret
# AUTH__PROVIDERS__AUTHELIA__OIDC__ISSUER=https://auth.local
# AUTH__PROVIDERS__AUTHELIA__OIDC__SHARING__ENABLED=true

Validation

Safebucket validates all configuration on startup. If required variables are missing or invalid, the application will exit with detailed error messages.