Environment Variables

This page provides a complete reference of all environment variables used to configure Isekai Core. Copy the example below to your .env file and fill in your own values.

Complete Configuration

# Isekai - Self-Hosted Configuration
# Copy this file to .env and fill in your own values

# =============================================================================
# Database Configuration
# =============================================================================
DATABASE_URL=postgresql://isekai:isekai@postgres:5432/isekai

# =============================================================================
# Redis Configuration
# =============================================================================
REDIS_URL=redis://redis:6379

# =============================================================================
# DeviantArt OAuth Configuration
# =============================================================================
# You MUST create your own DeviantArt OAuth application
# 1. Go to: https://www.deviantart.com/developers/apps
# 2. Create a new application
# 3. Required scopes: user, browse, stash, publish, note, message, gallery
# 4. Set redirect URI to: http://localhost:4000/api/auth/deviantart/callback
#    (or your production URL: https://api.example.com/api/auth/deviantart/callback)

DEVIANTART_CLIENT_ID=your_client_id_here
DEVIANTART_CLIENT_SECRET=your_client_secret_here
DEVIANTART_REDIRECT_URI=http://localhost:4000/api/auth/deviantart/callback

# Note: Frontend automatically uses DEVIANTART_CLIENT_ID via Vite config
# No need to set VITE_DEVIANTART_CLIENT_ID separately

# =============================================================================
# S3-Compatible Storage Configuration
# =============================================================================
# Supports: AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Backblaze B2
#
# DEFAULT: Uses local MinIO container (docker-compose.yml includes MinIO)
# The MinIO web console is available at: http://localhost:9001
# Login: minioadmin / minioadmin
#
# To use a different storage provider, override these values with one of:
#
# --- AWS S3 ---
# S3_ENDPOINT=                            # Leave empty for AWS
# S3_REGION=us-east-1
# S3_ACCESS_KEY_ID=AKIA...
# S3_SECRET_ACCESS_KEY=...
# S3_BUCKET_NAME=my-bucket
# S3_PUBLIC_URL=https://my-bucket.s3.us-east-1.amazonaws.com
# S3_FORCE_PATH_STYLE=false
#
# --- Cloudflare R2 ---
# S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
# S3_REGION=auto
# S3_ACCESS_KEY_ID=...
# S3_SECRET_ACCESS_KEY=...
# S3_BUCKET_NAME=isekai-uploads
# S3_PUBLIC_URL=https://pub-xxx.r2.dev
# S3_FORCE_PATH_STYLE=false
#
# --- DigitalOcean Spaces ---
# S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
# S3_REGION=nyc3
# S3_ACCESS_KEY_ID=...
# S3_SECRET_ACCESS_KEY=...
# S3_BUCKET_NAME=my-space
# S3_PUBLIC_URL=https://my-space.nyc3.cdn.digitaloceanspaces.com
# S3_FORCE_PATH_STYLE=false
#
# --- Backblaze B2 ---
# S3_ENDPOINT=https://s3.us-west-004.backblazeb2.com
# S3_REGION=us-west-004
# S3_ACCESS_KEY_ID=...
# S3_SECRET_ACCESS_KEY=...
# S3_BUCKET_NAME=my-bucket
# S3_PUBLIC_URL=https://f004.backblazeb2.com/file/my-bucket
# S3_FORCE_PATH_STYLE=false

# Default: Local MinIO (works out of the box with docker compose up)
S3_ENDPOINT=http://minio:9000
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET_NAME=isekai-uploads
S3_PUBLIC_URL=http://localhost:9000/isekai-uploads
S3_FORCE_PATH_STYLE=true

# =============================================================================
# Security Configuration
# =============================================================================
# Generate strong random values for these:
# SESSION_SECRET: Any random string (e.g., openssl rand -base64 32)
# ENCRYPTION_KEY: 32-byte hex key (e.g., openssl rand -hex 32)

SESSION_SECRET=change-this-to-a-random-string
ENCRYPTION_KEY=change-this-to-32-byte-hex-key

# Optional: Set to ".yourdomain.com" to share cookies across subdomains in production
# Leave empty for localhost development
COOKIE_DOMAIN=

# Session cookie lifetime in days (default: 7)
SESSION_MAX_AGE_DAYS=7

# DeviantArt refresh token tracking period in days (default: 90)
REFRESH_TOKEN_EXPIRY_DAYS=90

# =============================================================================
# Application URLs
# =============================================================================
FRONTEND_URL=http://localhost:3000
PORT=4000
NODE_ENV=production

# Frontend Runtime Configuration (Build Once, Run Anywhere)
# These variables are injected at container startup, not build time
# This allows the same Docker image to be deployed in different environments
VITE_API_URL=http://localhost:4000/api
VITE_DEVIANTART_CLIENT_ID=${DEVIANTART_CLIENT_ID}

# =============================================================================
# Session Storage Configuration
# =============================================================================
# Options: redis, postgres (auto-detects if not set)
SESSION_STORE=redis

# =============================================================================
# Cache Configuration
# =============================================================================
CACHE_ENABLED=true                    # Master switch for Redis caching
CACHE_DEFAULT_TTL=300                 # Default cache TTL in seconds (5 minutes)
CACHE_STALE_TTL=7200                  # Stale cache TTL for 429 fallback (2 hours)

# =============================================================================
# Circuit Breaker Configuration
# =============================================================================
CIRCUIT_BREAKER_ENABLED=true          # Enable circuit breaker for rate limiting
CIRCUIT_BREAKER_THRESHOLD=3           # Number of 429 errors before opening circuit
CIRCUIT_BREAKER_OPEN_DURATION_MS=300000  # Stay open for 5 minutes
CIRCUIT_BREAKER_PERSIST_TO_REDIS=true # Persist circuit state to Redis

# =============================================================================
# Publisher Worker Configuration
# =============================================================================
PUBLISHER_CONCURRENCY=5               # Number of concurrent jobs per worker
PUBLISHER_MAX_ATTEMPTS=7              # Max retry attempts for failed jobs
PUBLISHER_JOB_TIMEOUT_MS=600000       # Job timeout in milliseconds (10 minutes)
PUBLISHER_STALE_CHECK_INTERVAL_MS=60000  # Check for stalled jobs interval (1 minute)
PUBLISHER_MAX_STALLED_COUNT=2         # Max stalled attempts before failure

# =============================================================================
# Rate Limiter Configuration
# =============================================================================
RATE_LIMITER_ENABLED=true             # Enable adaptive rate limiter
RATE_LIMITER_BASE_DELAY_MS=3000       # Base delay between requests (3 seconds)
RATE_LIMITER_MAX_DELAY_MS=300000      # Max delay between requests (5 minutes)
RATE_LIMITER_JITTER_PERCENT=20        # Jitter percentage for delays
RATE_LIMITER_SUCCESS_DECREASE_FACTOR=0.9   # Decrease delay after success
RATE_LIMITER_FAILURE_INCREASE_FACTOR=2.0   # Increase delay after failure

# =============================================================================
# Metrics & Monitoring
# =============================================================================
METRICS_ENABLED=true                  # Enable metrics collection
METRICS_FLUSH_INTERVAL_MS=60000       # Flush metrics to Redis interval (1 minute)
LOG_LEVEL=info                        # Log level: debug, info, warn, error

# =============================================================================
# Health Check Configuration
# =============================================================================
HEALTH_CHECK_PORT=8000                # Port for publisher health check HTTP server
HEALTH_CHECK_ENABLED=true             # Enable health check endpoint

# =============================================================================
# Docker Image Tag
# =============================================================================
IMAGE_TAG=latest

Configuration Sections Explained

Required Configuration

These variables must be set for Isekai to function:

DEVIANTART_CLIENT_ID & DEVIANTART_CLIENT_SECRET: OAuth credentials from DeviantArt
SESSION_SECRET & ENCRYPTION_KEY: Security keys for session management and token encryption

Storage Configuration

Storage is pre-configured for local development using MinIO. For production, configure one of the supported S3-compatible providers:

Variable	Description	Default
`S3_ENDPOINT`	S3 API endpoint. Leave empty for AWS S3.	`http://minio:9000`
`S3_REGION`	Bucket region	`us-east-1`
`S3_ACCESS_KEY_ID`	Access key	`minioadmin`
`S3_SECRET_ACCESS_KEY`	Secret key	`minioadmin`
`S3_BUCKET_NAME`	Bucket name	`isekai-uploads`
`S3_PUBLIC_URL`	Public URL for files	`http://localhost:9000/isekai-uploads`
`S3_FORCE_PATH_STYLE`	Path-style URLs (required for MinIO)	`true`

See the Storage Setup guide for detailed instructions on each provider.

Optional Tuning

These variables have defaults but can be adjusted based on your needs:

Publisher Configuration: Control job concurrency and retry behavior
Rate Limiter: Adjust API call delays to balance speed vs. compliance
Circuit Breaker: Configure automatic protection against rate limiting
Cache Settings: Control Redis caching behavior

Instance Configuration

These variables control instance-level features. All are optional with sensible defaults.

Variable	Default	Description
`MAX_DA_ACCOUNTS`	`0`	Maximum DeviantArt accounts allowed. `0` = unlimited.
`TEAM_INVITES_ENABLED`	`false`	Allow inviting team members to share the instance.

Whitelabeling (Optional)

Customize the branding of your Isekai instance. All variables are optional.

Variable	Default	Description
`WHITELABEL_ENABLED`	`false`	Enable custom branding.
`WHITELABEL_PRODUCT_NAME`	`Isekai`	Custom product name shown in the UI.
`WHITELABEL_LOGO_URL`	-	URL to custom logo image.
`WHITELABEL_FAVICON_URL`	-	URL to custom favicon.
`WHITELABEL_FOOTER_TEXT`	-	Custom footer text.
`WHITELABEL_SUPPORT_EMAIL`	-	Support email address shown in the UI.