Skip to main content

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​

VariableDescriptionDefaultRequiredValid Values
APP__LOG_LEVELLogging level for the applicationinfo❌debug, info, warn, error, fatal, panic
APP__API_URLAPI base URL-✅-
APP__WEB_URLFrontend web URL-✅-
APP__PORTServer port (80-65535)8080❌80-65535
APP__JWT_SECRETJWT signing secret-✅-
APP__ADMIN_EMAILAdmin user email-✅Valid email
APP__ADMIN_PASSWORDAdmin user password-✅-
APP__TRASH_RETENTION_DAYSDays to retain files in trash before automatic deletion7❌1-365

CORS and Security​

VariableDescriptionDefaultRequired
APP__ALLOWED_ORIGINSComma-separated allowed origins-✅
APP__TRUSTED_PROXIESComma-separated trusted proxy IPs-✅

Example:

APP__API_URL=http://localhost:1323
APP__WEB_URL=http://localhost:3001
APP__PORT=1323
APP__JWT_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​

VariableDescriptionDefaultRequired
APP__STATIC_FILES__ENABLEDEnable static file servingtrue❌
APP__STATIC_FILES__DIRECTORYStatic files directoryweb/dist❌

Database Configuration​

VariableDescriptionDefaultRequired
DATABASE__HOSTPostgreSQL host-✅
DATABASE__PORTPostgreSQL port5432❌
DATABASE__USERDatabase username-✅
DATABASE__PASSWORDDatabase password-✅
DATABASE__NAMEDatabase name-✅
DATABASE__SSLMODESSL modedisable❌

Example:

DATABASE__HOST=localhost
DATABASE__PORT=5442
DATABASE__USER=root
DATABASE__PASSWORD=root
DATABASE__NAME=safebucket
DATABASE__SSLMODE=disable

Authentication Configuration​

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

Storage Configuration​

Basic Storage Settings​

VariableDescriptionDefaultRequired
STORAGE__TYPEStorage provider type (rustfs, minio, aws, gcp)-✅

For detailed storage provider configuration including RustFS, MinIO, AWS S3, and Google Cloud Storage setup, see the Storage Providers page.

Cache Configuration​

Safebucket supports Redis and Valkey for caching.

Redis​

VariableDescriptionDefaultRequired
CACHE__TYPECache type (redis or valkey)-✅
CACHE__REDIS__HOSTSComma-separated Redis hosts-✅ (if Redis)
CACHE__REDIS__PASSWORDRedis password-❌
CACHE__REDIS__TLS_ENABLEDEnable TLS for Redis connectionfalse❌
CACHE__REDIS__TLS_SERVER_NAMETLS server name for Redis-❌

Valkey​

VariableDescriptionDefaultRequired
CACHE__VALKEY__HOSTSComma-separated Valkey hosts-✅ (if Valkey)
CACHE__VALKEY__PASSWORDValkey password-❌
CACHE__VALKEY__TLS_ENABLEDEnable TLS for Valkey connectionfalse❌
CACHE__VALKEY__TLS_SERVER_NAMETLS server name for Valkey-❌

Example:

CACHE__TYPE=redis
CACHE__REDIS__HOSTS=localhost:6379
CACHE__REDIS__PASSWORD=root

Events Configuration​

Safebucket supports multiple event systems for real-time notifications. Events are configured separately from storage and use a queue-based architecture for different event types.

NATS JetStream​

VariableDescriptionDefaultRequired
EVENTS__TYPEEvent system type-✅
EVENTS__JETSTREAM__HOSTNATS host-✅ (if JetStream)
EVENTS__JETSTREAM__PORTNATS port-✅ (if JetStream)

Queue Configuration​

Safebucket uses multiple queues for different event types:

VariableDescriptionRequired
EVENTS__QUEUES__NOTIFICATIONS__NAMEUser notification events queue✅ (if JetStream)
EVENTS__QUEUES__BUCKET_EVENTS__NAMEBucket event notifications✅ (if JetStream)
EVENTS__QUEUES__OBJECT_DELETION__NAMEObject deletion events queue✅ (if JetStream)

Example:

EVENTS__TYPE=jetstream
EVENTS__JETSTREAM__HOST=localhost
EVENTS__JETSTREAM__PORT=4222

# Queue names
EVENTS__QUEUES__NOTIFICATIONS__NAME=safebucket-notifications
EVENTS__QUEUES__BUCKET_EVENTS__NAME=safebucket-bucket-events
EVENTS__QUEUES__OBJECT_DELETION__NAME=safebucket-object-deletion

Google Cloud Pub/Sub​

VariableDescriptionDefaultRequired
EVENTS__TYPEEvent system type-✅
EVENTS__GCP__PROJECT_IDGCP project ID-✅ (if GCP)
EVENTS__GCP__SUBSCRIPTION_SUFFIXSuffix for PubSub subscriptions-sub❌

AWS SQS​

VariableDescriptionDefaultRequired
EVENTS__TYPEEvent system type-✅
EVENTS__AWS__REGIONAWS region-✅ (if AWS)
EVENTS__AWS__ACCOUNT_IDAWS account ID-✅ (if AWS)
EVENTS__AWS__SQS_NAMESQS queue name-✅ (if AWS)

Email Configuration​

SMTP Settings​

VariableDescriptionDefaultRequired
NOTIFIER__TYPENotification typesmtp✅
NOTIFIER__SMTP__HOSTSMTP server host-✅
NOTIFIER__SMTP__PORTSMTP server port-✅
NOTIFIER__SMTP__USERNAMESMTP username-❌
NOTIFIER__SMTP__PASSWORDSMTP password-❌
NOTIFIER__SMTP__SENDERFrom email address-✅
NOTIFIER__SMTP__ENABLE_TLSEnable TLStrue❌
NOTIFIER__SMTP__SKIP_VERIFY_TLSSkip TLS verificationfalse❌

Example:

NOTIFIER__TYPE=smtp
NOTIFIER__SMTP__HOST=localhost
NOTIFIER__SMTP__PORT=1025
NOTIFIER__SMTP__USERNAME=root
NOTIFIER__SMTP__PASSWORD=root
[email protected]
NOTIFIER__SMTP__ENABLE_TLS=false
NOTIFIER__SMTP__SKIP_VERIFY_TLS=true

Activity Logging​

Loki Configuration​

VariableDescriptionDefaultRequired
ACTIVITY__TYPEActivity logger typeloki✅
ACTIVITY__LOKI__ENDPOINTLoki endpoint URL (must be valid HTTP)-✅

Example:

ACTIVITY__TYPE=loki
ACTIVITY__LOKI__ENDPOINT=http://localhost:3100

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__JWT_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__HOST=localhost
DATABASE__PORT=5432
DATABASE__USER=safebucket-user
DATABASE__PASSWORD=safebucket-password
DATABASE__NAME=safebucket
DATABASE__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__ENABLE_TLS=true
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.