Configuration
This guide covers all configuration options available when self-hosting Colanode. Configuration is primarily done through environment variables, making it easy to adapt to different deployment environments.
Server
SERVER_NAME*
Display name shown in client apps. For example Colanode Cloud EU.
SERVER_AVATAR
URL for the server avatar image. Default: (empty).
SERVER_MODE
Determines whether the server runs as a standalone instance or as a cluster of nodes. This setting controls cross‑node propagation of changes. For single‑node deployments, set this to standalone to avoid publishing events to Redis.
Values: standalone
or cluster
. Default: standalone
.
SERVER_PATH_PREFIX
Optional custom path prefix applied to all server URLs. Useful when running Colanode behind an API gateway alongside other services/APIs.
For example, if SERVER_PATH_PREFIX="colanode"
, the path https://gateway.example.com/client/v1/avatars
becomes https://gateway.example.com/colanode/client/v1/avatars
.
Default: (empty).
SERVER_NAME="My Company Colanode"
SERVER_AVATAR="https://example.com/logo.png"
SERVER_MODE=standalone
CORS
Control which origins can access your Colanode server. These settings apply only when using Colanode from the web client; the desktop client is not affected by CORS.
SERVER_CORS_ORIGIN
Allowed origins (comma-separated) or *
for all. Default: http://localhost:4000
.
SERVER_CORS_MAX_AGE
Maximum age in seconds for caching CORS preflight responses. Optional.
# Allow multiple origins
SERVER_CORS_ORIGIN="https://colanode.company.com,https://app.company.com"
# Allow all origins (not recommended for production)
SERVER_CORS_ORIGIN="*"
Postgres
Colanode requires PostgreSQL with the pgvector
extension:
POSTGRES_URL*
Complete PostgreSQL connection string.
POSTGRES_SSL_REJECT_UNAUTHORIZED
Reject unauthorized SSL certificates (true
/false
).
POSTGRES_SSL_CA
SSL Certificate Authority certificate.
POSTGRES_SSL_KEY
SSL private key.
POSTGRES_SSL_CERT
SSL certificate.
# Basic connection
POSTGRES_URL="postgres://username:password@localhost:5432/colanode_db"
# SSL connection
POSTGRES_URL="postgres://username:password@db.example.com:5432/colanode_db?sslmode=require"
POSTGRES_SSL_REJECT_UNAUTHORIZED="false"
Redis
REDIS_URL*
Redis connection string.
REDIS_DB
Redis database number. Default: 0
.
REDIS_JOBS_QUEUE_NAME
Job queue name. Default: jobs
.
REDIS_JOBS_QUEUE_PREFIX
Queue prefix. Default: colanode
.
REDIS_EVENTS_CHANNEL
Events channel name. Default: events
.
# Basic Redis connection
REDIS_URL="redis://localhost:6379/0"
# Redis with authentication
REDIS_URL="redis://:password@localhost:6379/0"
# Redis cluster or cloud service
REDIS_URL="rediss://username:password@redis.example.com:6380/0"
Storage
STORAGE_S3_ENDPOINT*
S3 service endpoint URL.
STORAGE_S3_ACCESS_KEY*
S3 access key.
STORAGE_S3_SECRET_KEY*
S3 secret key.
STORAGE_S3_BUCKET*
S3 bucket name.
STORAGE_S3_REGION*
S3 region.
STORAGE_S3_FORCE_PATH_STYLE
Use path-style URLs (required for MinIO).
# MinIO configuration
STORAGE_S3_ENDPOINT="http://minio:9000"
STORAGE_S3_ACCESS_KEY="minioadmin"
STORAGE_S3_SECRET_KEY="your_secret_key"
STORAGE_S3_BUCKET="colanode"
STORAGE_S3_REGION="us-east-1"
STORAGE_S3_FORCE_PATH_STYLE="true"
# AWS S3 configuration
STORAGE_S3_ENDPOINT="https://s3.us-west-2.amazonaws.com"
STORAGE_S3_ACCESS_KEY="AKIA..."
STORAGE_S3_SECRET_KEY="..."
STORAGE_S3_BUCKET="my-colanode-bucket"
STORAGE_S3_REGION="us-west-2"
STORAGE_S3_FORCE_PATH_STYLE="false"
Account
Control how new accounts are verified:
ACCOUNT_VERIFICATION_TYPE
Controls verification for new registrations. Options:
automatic
— all new accounts are automatically marked as verified; no action is needed.manual
— server administrators verify accounts manually. To verify an account, set thestatus
column to1
(integer) in theaccounts
table in the Postgres database.email
— sends a verification code to the account email address. Requires SMTP to be enabled and configured.
Default: automatic
.
ACCOUNT_OTP_TIMEOUT
OTP timeout in seconds. Used only when account verification type is set to email
. Default: 600
.
# Automatic verification (no admin approval needed)
ACCOUNT_VERIFICATION_TYPE="automatic"
# Manual verification (admin approval required)
ACCOUNT_VERIFICATION_TYPE="manual"
# Email verification (requires SMTP configuration)
ACCOUNT_VERIFICATION_TYPE="email"
ACCOUNT_OTP_TIMEOUT="300"
Google Auth
Enable Google authentication. Works only on the web client for now. See Google guide to obtain a client ID and client secret.
ACCOUNT_GOOGLE_ENABLED
Enable Google OAuth.
ACCOUNT_GOOGLE_CLIENT_ID
Google OAuth client ID.
ACCOUNT_GOOGLE_CLIENT_SECRET
Google OAuth client secret.
ACCOUNT_GOOGLE_ENABLED="true"
ACCOUNT_GOOGLE_CLIENT_ID="your_google_client_id"
ACCOUNT_GOOGLE_CLIENT_SECRET="your_google_client_secret"
Workspace
Set default limits for workspace storage and file uploads
WORKSPACE_STORAGE_LIMIT
Default total storage allowed per workspace, in bytes. Administrators can change this per workspace manually in Postgres database. Default: (empty - unlimited).
WORKSPACE_MAX_FILE_SIZE
Default maximum upload size per workspace, in bytes. Administrators can change this per workspace manually in Postgres database. Default: (empty - unlimited).
# 20GB storage limit per workspace
WORKSPACE_STORAGE_LIMIT="21474836480"
# 500MB maximum file size
WORKSPACE_MAX_FILE_SIZE="524288000"
User
Set default limits for user storage and file uploads
USER_STORAGE_LIMIT
Default total storage allowed per user, in bytes. Administrators can change this per workspace via the client UI. Default: 10737418240
(10 GB).
USER_MAX_FILE_SIZE
Default maximum upload size per user, in bytes. Administrators can change this per workspace via the client UI. Default: 104857600
(100 MB).
# 20GB storage limit per user
USER_STORAGE_LIMIT="21474836480"
# 500MB maximum file size
USER_MAX_FILE_SIZE="524288000"
SMTP
Configure email delivery for notifications and verification:
SMTP_ENABLED*
Enable SMTP email delivery. Default: false
.
SMTP_HOST
SMTP server hostname. Required when SMTP_ENABLED="true"
.
SMTP_PORT
SMTP server port. Required when SMTP_ENABLED="true"
.
SMTP_USER
SMTP username. Optional.
SMTP_PASSWORD
SMTP password. Optional.
SMTP_EMAIL_FROM
From email address. Required when SMTP_ENABLED="true"
.
SMTP_EMAIL_FROM_NAME
From display name. Optional.
# Disable email (default)
SMTP_ENABLED="false"
# Production SMTP configuration
SMTP_ENABLED="true"
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"
SMTP_EMAIL_FROM="noreply@yourcompany.com"
SMTP_EMAIL_FROM_NAME="Your Company Colanode"
# Local testing with Mailpit
SMTP_ENABLED="true"
SMTP_HOST="mailpit"
SMTP_PORT="1025"
SMTP_EMAIL_FROM="test@localhost"
SMTP_EMAIL_FROM_NAME="Colanode Local"