logo
Configuration
Configuration

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 the status column to 1 (integer) in the accounts 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"