Kokomo
Back to Documentation

Self-Hosting

Configuration

Complete reference for all environment variables and configuration options.

Server Settings

Core server configuration options.

VariableDefaultDescription
ENVproductionEnvironment mode (development, staging, production)
PORT8080HTTP/WebSocket server port
HOST0.0.0.0Server host (0.0.0.0 = all interfaces)
BASE_URL*-Application base URL (e.g., https://kokomo.yourdomain.com)
LOG_LEVELinfoLogging level (debug, info, warn, error)
LOG_FILE/var/log/kokomo/app.logLog file path
LOG_JSONtrueJSON format logging

Database (PostgreSQL)

PostgreSQL connection settings.

VariableDefaultDescription
DB_HOST*localhostDatabase host (use 'postgres' for Docker)
DB_PORT5432Database port
DB_USER*kokomoDatabase username
DB_PASSWORD*-Database password
DB_NAME*kokomoDatabase name
DB_SSLMODEdisableSSL mode (disable, require, verify-ca, verify-full)
DB_MAX_CONNECTIONS25Maximum connection pool size
DB_MAX_IDLE_CONNECTIONS5Maximum idle connections
DB_MAX_LIFETIME_MINUTES60Connection max lifetime
Connection URL format
# Can also use DATABASE_URL instead of individual vars
DATABASE_URL=postgres://kokomo:password@localhost:5432/kokomo?sslmode=disable

JWT Authentication

Token-based authentication settings.

VariableDefaultDescription
JWT_SECRET*-Access token secret (min 32 chars)
JWT_REFRESH_SECRET*-Refresh token secret (different from JWT_SECRET)
JWT_EXPIRATION_MINUTES15Access token expiration (minutes)
JWT_REFRESH_EXPIRATION_DAYS7Refresh token expiration (days)
Generate JWT Secrets
# Generate 64-character hex secrets
openssl rand -hex 64

# Example output:
# a1b2c3d4e5f6...

File Storage

Configure local or S3-compatible storage.

VariableDefaultDescription
UPLOAD_DIR/var/kokomo/uploadsUpload directory path
MAX_UPLOAD_SIZE_MB50Max file upload size (MB)
THUMBNAIL_DIRthumbnailsThumbnail subdirectory
ALLOWED_FILE_EXTENSIONSjpg,jpeg,png,gif,pdf,doc,docx,mp4Allowed file extensions (comma-separated)

S3 Storage (Optional)

VariableDefaultDescription
USE_S3falseEnable S3 storage
AWS_REGIONap-northeast-2AWS region
AWS_ACCESS_KEY_ID-AWS access key
AWS_SECRET_ACCESS_KEY-AWS secret key
S3_BUCKET-S3 bucket name
S3_ENDPOINT-Custom endpoint (for MinIO, etc.)

Redis (Optional)

Caching and session storage settings.

VariableDefaultDescription
USE_REDISfalseEnable Redis caching
REDIS_HOSTlocalhostRedis host (use 'redis' for Docker)
REDIS_PORT6379Redis port
REDIS_PASSWORD-Redis password (if set)
REDIS_DB0Redis database number
Redis URL format
# Can also use REDIS_URL
REDIS_URL=redis://localhost:6379
REDIS_URL=redis://:password@localhost:6379/0

CORS Settings

Cross-Origin Resource Sharing configuration.

VariableDefaultDescription
CORS_ALLOWED_ORIGINS*Allowed origins (comma-separated, or * for all)
CORS_ALLOWED_METHODSGET,POST,PUT,DELETE,OPTIONS,PATCHAllowed HTTP methods
CORS_ALLOWED_HEADERSOrigin,Content-Type,Accept,AuthorizationAllowed headers
CORS_ALLOW_CREDENTIALStrueAllow credentials (cookies, auth headers)

Rate Limiting

DDoS protection and API rate limiting.

VariableDefaultDescription
RATE_LIMIT_ENABLEDtrueEnable rate limiting
RATE_LIMIT_WINDOW_SECONDS60Time window (seconds)
RATE_LIMIT_MAX_REQUESTS100Max requests per window

WebSocket

Real-time communication settings.

VariableDefaultDescription
WEBSOCKET_PATH/wsWebSocket endpoint path
WEBSOCKET_MAX_MESSAGE_SIZE1048576Max message size (1MB)
WEBSOCKET_READ_BUFFER_SIZE1024Read buffer size
WEBSOCKET_WRITE_BUFFER_SIZE1024Write buffer size

Email (SMTP)

Configure email for invitations and notifications.

VariableDefaultDescription
SMTP_HOST-SMTP server hostname
SMTP_PORT587SMTP port
SMTP_USER-SMTP username
SMTP_PASSWORD-SMTP password
SMTP_FROM-From address for emails
Example SMTP Configs
# Gmail
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

# AWS SES
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-access-key
SMTP_PASSWORD=your-ses-secret-key

Security

Security and protection settings.

VariableDefaultDescription
FORCE_HTTPStrueForce HTTPS (recommended for production)
TRUSTED_PROXIES127.0.0.1,::1Trusted proxy IPs
CSRF_ENABLEDtrueEnable CSRF protection
CSRF_SECRET-CSRF token secret

Monitoring

Health check and metrics endpoints.

VariableDefaultDescription
METRICS_ENABLEDtrueEnable Prometheus metrics
METRICS_PATH/metricsMetrics endpoint path
HEALTH_CHECK_PATH/healthHealth check endpoint

Complete Example

A production-ready configuration example.

.env
# ===================
# Kokomo Server Config
# ===================

# Server
ENV=production
PORT=8080
HOST=0.0.0.0
BASE_URL=https://kokomo.yourcompany.com

# Database (PostgreSQL)
DB_HOST=postgres
DB_PORT=5432
DB_USER=kokomo
DB_PASSWORD=your-secure-db-password-here
DB_NAME=kokomo
DB_SSLMODE=disable
DB_MAX_CONNECTIONS=25

# JWT Authentication
JWT_SECRET=your-64-character-random-hex-string-for-access-tokens
JWT_REFRESH_SECRET=another-64-character-random-hex-string-for-refresh
JWT_EXPIRATION_MINUTES=15
JWT_REFRESH_EXPIRATION_DAYS=7

# Redis
USE_REDIS=true
REDIS_HOST=redis
REDIS_PORT=6379

# File Storage
UPLOAD_DIR=/var/kokomo/uploads
MAX_UPLOAD_SIZE_MB=50
ALLOWED_FILE_EXTENSIONS=jpg,jpeg,png,gif,pdf,doc,docx,xls,xlsx,ppt,pptx,zip,mp4,mov

# CORS
CORS_ALLOWED_ORIGINS=https://kokomo.yourcompany.com,https://app.yourcompany.com

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_SECONDS=60
RATE_LIMIT_MAX_REQUESTS=100

# Security
FORCE_HTTPS=true
CSRF_ENABLED=true
CSRF_SECRET=your-csrf-secret-here

# Email (optional)
SMTP_HOST=smtp.yourcompany.com
SMTP_PORT=587
SMTP_USER=kokomo@yourcompany.com
SMTP_PASSWORD=email-password
SMTP_FROM=Kokomo <kokomo@yourcompany.com>

# Logging
LOG_LEVEL=info
LOG_JSON=true
Installation GuideDatabase Setup
SANDBOX MODE