logo
Configuration
Configuration

Configuration

This guide covers all configuration options available when self-hosting Colanode. config.json is the primary source of truth and ships inside the server image. Environment variables are only used to hold secrets or specific overrides referenced by the configuration file.

Configuration workflow

  1. Sensible defaults are built-in. The server runs with reasonable defaults out of the box. You only need a custom config.json when you want to change specific settings.
  2. Override with a config file. Set the CONFIG environment variable to point to your JSON file (e.g., CONFIG=/path/to/config.json). The file only needs to contain the fields you want to override; missing fields use defaults.
  3. Secrets stay in env vars. In config.json, reference secrets with env://VAR_NAME. At runtime the loader resolves those pointers from the process environment.
  4. File contents. You can also inline file contents (like certificates) using file://path/to/file.
  5. Precedence: Custom config values > schema defaults. Environment variables do not automatically override config values unless the config explicitly references them via env://.

Deployment-specific steps

  • Docker Compose: The server works out of the box with default file storage. To customize, create a config.json and mount it as a volume, then set CONFIG=/config.json in the environment block. See hosting/docker/docker-compose.yaml.
  • Helm/Kubernetes: Enable colanode.configFile.enabled and pass your JSON via --set-file colanode.configFile.data=./config.json (see Kubernetes guide).

Required environment variables

These must always be provided because the stock config.json references them with env://…:

PurposeJSON pathEnv var
PostgreSQL URLpostgres.urlPOSTGRES_URL
Redis URLredis.urlREDIS_URL

Server

Core server settings are configured at the root level of config.json.

name

Display name shown in client apps. For example Colanode Cloud EU. Default: Colanode Server.

avatar

URL for the server avatar image. Default: null.

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.

pathPrefix

Optional custom path prefix applied to all server URLs. Useful when running Colanode behind an API gateway alongside other services/APIs.

For example, if pathPrefix="colanode", the path https://gateway.example.com/client/v1/avatars becomes https://gateway.example.com/colanode/client/v1/avatars.

Default: none.

{
  "name": "My Company Colanode",
  "avatar": "https://example.com/logo.png",
  "mode": "standalone",
  "pathPrefix": "colanode"
}

CORS

Configure under the cors object at the root level.

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.

origin

Allowed origins. Can be:

  • A string: "https://app.example.com"
  • An array of strings: ["https://app1.example.com", "https://app2.example.com"]
  • A boolean: true to allow all origins, false to deny all

Default: http://localhost:4000.

maxAge

Maximum age in seconds for caching CORS preflight responses. Default: 7200.

{
  "cors": {
    "origin": ["https://colanode.company.com", "https://app.company.com"],
    "maxAge": 7200
  }
}

Postgres

Configure under the postgres object.

Colanode requires PostgreSQL with the pgvector extension.

url

Complete PostgreSQL connection string. Defaults to env://POSTGRES_URL.

ssl

SSL configuration object.

  • rejectUnauthorized: Reject unauthorized SSL certificates (true/false).
  • ca: SSL Certificate Authority certificate (string or file://...).
  • key: SSL private key.
  • cert: SSL certificate.
{
  "postgres": {
    "url": "env://POSTGRES_URL",
    "ssl": {
      "rejectUnauthorized": false,
      "ca": "file://certs/ca.pem"
    }
  }
}

Redis

Configure under the redis object.

url

Redis connection string. Defaults to env://REDIS_URL.

db

Redis database number. Default: 0.

eventsChannel

Pub/Sub channel name for real-time events (used in cluster mode). Default: events.

{
  "redis": {
    "url": "env://REDIS_URL",
    "db": 0,
    "eventsChannel": "events"
  }
}

Storage

Colanode supports multiple storage backends. Configure storage under the storage object, which contains two sub-objects: provider (the storage backend) and tus (resumable upload settings).

Default behavior: Without any configuration, Colanode uses file system storage with the ./data directory.

File System Storage

Store files directly on the server’s filesystem. This is the default storage backend.

provider.type

Set to file.

provider.directory

Directory path where files will be stored (must be writable). Default: ./data.

{
  "storage": {
    "provider": {
      "type": "file",
      "directory": "/var/lib/colanode/storage"
    }
  }
}

Notes:

  • Ensure the directory exists and has proper permissions
  • For Docker, mount a volume at the specified path
  • For Kubernetes, configure persistent volume claims

S3-Compatible Storage

Store files in S3-compatible object storage (AWS S3, MinIO, Cloudflare R2, Backblaze B2, etc.).

provider.type

Set to s3.

provider.endpoint

S3 service endpoint URL.

provider.accessKey

S3 access key.

provider.secretKey

S3 secret key.

provider.bucket

S3 bucket name.

provider.region

S3 region.

provider.forcePathStyle

Use path-style URLs (required for MinIO). Optional.

{
  "storage": {
    "provider": {
      "type": "s3",
      "endpoint": "http://minio:9000",
      "bucket": "colanode",
      "region": "us-east-1",
      "forcePathStyle": true,
      "accessKey": "env://S3_ACCESS_KEY",
      "secretKey": "env://S3_SECRET_KEY"
    }
  }
}

Google Cloud Storage (GCS)

Store files in Google Cloud Storage.

provider.type

Set to gcs.

provider.bucket

GCS bucket name.

provider.projectId

Google Cloud project ID.

provider.credentials

Path to GCP service account JSON key file, or the JSON content itself. Can use file:// or env:// references.

{
  "storage": {
    "provider": {
      "type": "gcs",
      "bucket": "my-colanode-bucket",
      "projectId": "my-project-123",
      "credentials": "/path/to/service-account.json"
    }
  }
}

Setup Steps:

  1. Create a GCS bucket in Google Cloud Console
  2. Create a service account with Storage Object Admin permissions
  3. Download the service account JSON key
  4. Mount or copy the key file to the server
  5. Set provider.credentials to the file path using file:// prefix

Azure Blob Storage

Store files in Azure Blob Storage.

provider.type

Set to azure.

provider.account

Azure storage account name.

provider.containerName

Blob container name.

provider.accountKey

Storage account access key.

{
  "storage": {
    "provider": {
      "type": "azure",
      "account": "mystorageaccount",
      "containerName": "colanode",
      "accountKey": "env://AZURE_STORAGE_ACCOUNT_KEY"
    }
  }
}

Setup Steps:

  1. Create a storage account in Azure Portal
  2. Create a blob container within the storage account
  3. Get the account key from Access Keys section
  4. Configure the config file and environment variables

TUS (Resumable Uploads)

Colanode uses the TUS protocol for resumable file uploads. Configure TUS settings under storage.tus.

tus.locker

Controls how upload locks are managed to prevent concurrent writes to the same upload.

  • type: "memory" — In-memory locking. Simple but doesn’t work across multiple server instances. Default.
  • type: "redis" — Redis-based distributed locking. Required for multi-node deployments.

tus.cache

Controls caching of upload metadata.

  • type: "none" — No caching. Default.
  • type: "redis" — Cache upload metadata in Redis for faster lookups.
{
  "storage": {
    "tus": {
      "locker": {
        "type": "redis",
        "prefix": "colanode:tus:lock"
      },
      "cache": {
        "type": "none"
      }
    },
    "provider": {
      "type": "file",
      "directory": "/var/lib/colanode/storage"
    }
  }
}

Recommendation: For production deployments with multiple server instances, use redis locker to ensure upload consistency.

Account

Control how new accounts are verified under the account object.

verificationType

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 Email/SMTP to be enabled and configured.

Default: automatic.

otpTimeout

OTP timeout in seconds. Used only when account verification type is set to email. Default: 600.

{
  "account": {
    "verificationType": "email",
    "otpTimeout": 300
  }
}

Google Auth

Enable Google authentication under account.google. Works only on the web client for now. See Google guide to obtain a client ID and client secret.

enabled

Enable Google OAuth.

clientId

Google OAuth client ID.

clientSecret

Google OAuth client secret.

{
  "account": {
    "google": {
      "enabled": true,
      "clientId": "env://GOOGLE_CLIENT_ID",
      "clientSecret": "env://GOOGLE_CLIENT_SECRET"
    }
  }
}

Workspace

Set default limits for file uploads under the workspace object.

maxFileSize

Default maximum upload size per file in bytes. This is the global default; workspace administrators can adjust this per workspace. Default: 524288000 (500 MB).

{
  "workspace": {
    "maxFileSize": "524288000"
  }
}

Email (SMTP)

Configure email delivery for notifications and verification under the email object.

enabled

Enable email delivery. Default: false.

from.email

From email address. Required when enabled.

from.name

From display name. Optional.

provider

Configuration for the email provider. Currently supports smtp.

  • type: Must be smtp.
  • host: SMTP server hostname.
  • port: SMTP server port.
  • secure: Use TLS (true/false).
  • auth.user: SMTP username.
  • auth.password: SMTP password.
{
  "email": {
    "enabled": true,
    "from": {
      "email": "noreply@yourcompany.com",
      "name": "Your Company Colanode"
    },
    "provider": {
      "type": "smtp",
      "host": "smtp.gmail.com",
      "port": 587,
      "secure": false,
      "auth": {
        "user": "env://SMTP_USER",
        "password": "env://SMTP_PASSWORD"
      }
    }
  }
}

Jobs

Configure background job processing under the jobs object.

Queue Settings

queue.name

Name of the job queue. Default: jobs.

queue.prefix

Redis key prefix for the queue. Default: colanode.

Background Jobs

Colanode has several optional background jobs that can be enabled for maintenance tasks.

nodeUpdatesMerge

Merges node update history records to reduce database size.

  • enabled: Enable the job. Default: false.
  • cron: Cron schedule pattern. Default: 0 5 */2 * * * (every 2 hours).
  • batchSize: Number of records to process per run. Default: 500.
  • mergeWindow: Time window in seconds for merging updates. Default: 3600 (1 hour).
  • cutoffWindow: Minimum age in seconds before updates can be merged. Default: 7200 (2 hours).

documentUpdatesMerge

Merges document update history records to reduce database size.

  • enabled: Enable the job. Default: false.
  • cron: Cron schedule pattern. Default: 0 5 */2 * * *.
  • batchSize: Number of records to process per run. Default: 500.
  • mergeWindow: Time window in seconds for merging updates. Default: 3600.
  • cutoffWindow: Minimum age in seconds before updates can be merged. Default: 7200.

cleanup

Runs cleanup tasks for orphaned data.

  • enabled: Enable the job. Default: false.
  • cron: Cron schedule pattern. Default: 0 5 */2 * * *.
{
  "jobs": {
    "queue": {
      "name": "jobs",
      "prefix": "colanode"
    },
    "nodeUpdatesMerge": {
      "enabled": true,
      "cron": "0 5 */2 * * *",
      "batchSize": 500,
      "mergeWindow": 3600,
      "cutoffWindow": 7200
    },
    "documentUpdatesMerge": {
      "enabled": true,
      "cron": "0 5 */2 * * *",
      "batchSize": 500,
      "mergeWindow": 3600,
      "cutoffWindow": 7200
    },
    "cleanup": {
      "enabled": true,
      "cron": "0 5 */2 * * *"
    }
  }
}

Logging

Configure server logging under the logging object.

level

Log level. Options: trace, debug, info, warn, error, fatal, silent. Default: info.

{
  "logging": {
    "level": "info"
  }
}