Runtime configuration

This guide covers all available configuration options for self-hosted Convex deployments.

Environment variables

All configuration is done through environment variables. These can be set in:

A .env file next to your docker-compose.yml
Directly in your docker-compose.yml file
Through your hosting platform’s configuration (Fly.io secrets, Railway variables, etc.)

Core configuration

Instance configuration

INSTANCE_NAME

string

default:"convex-self-hosted"

Name of your Convex instance. This determines the database name (with - replaced by _).

INSTANCE_SECRET

string

Secret key for your instance. Keep this very safe and only accessible from the backend. Required when running the binary directly.

URL configuration

CONVEX_CLOUD_ORIGIN

string

default:"http://127.0.0.1:3210"

URL of the Convex API as accessed by clients and the frontend.

CONVEX_CLOUD_ORIGIN='https://api.my-domain.com'

CONVEX_SITE_ORIGIN

string

default:"http://127.0.0.1:3211"

URL of Convex HTTP actions as accessed by clients and the frontend.

CONVEX_SITE_ORIGIN='https://my-domain.com'

NEXT_PUBLIC_DEPLOYMENT_URL

string

default:"http://127.0.0.1:3210"

URL of the Convex API as accessed by the dashboard (browser).

NEXT_PUBLIC_DEPLOYMENT_URL='https://api.my-domain.com'

Port configuration

PORT

number

default:"3210"

Port for the Convex backend API.

SITE_PROXY_PORT

number

default:"3211"

Port for HTTP actions.

DASHBOARD_PORT

number

default:"6791"

Port for the dashboard web interface.

Database configuration

DATABASE_URL

string

Generic database connection string. For specific databases, use POSTGRES_URL or MYSQL_URL instead.

POSTGRES_URL

string

PostgreSQL connection string without database name and query parameters.

POSTGRES_URL='postgresql://user:[email protected]'

The backend will connect to a database named after your instance (e.g., convex_self_hosted).

MYSQL_URL

string

MySQL connection string without database name and query parameters.

MYSQL_URL='mysql://user:[email protected]'

DO_NOT_REQUIRE_SSL

boolean

default:"false"

Disable SSL requirement for database connections. Useful for local development.

Only set this to true for local development. Production deployments should use SSL.

DO_NOT_REQUIRE_SSL=1

S3 storage configuration

AWS_REGION

string

AWS region for S3 buckets.

AWS_REGION='us-east-1'

AWS_ACCESS_KEY_ID

string

AWS access key ID for S3 authentication.

AWS_SECRET_ACCESS_KEY

string

AWS secret access key for S3 authentication.

Never commit AWS credentials to source control. Use environment variables or secrets management.

AWS_SESSION_TOKEN

string

AWS session token for temporary credentials.

S3_ENDPOINT_URL

string

Custom S3 endpoint URL. Required for S3-compatible services like Cloudflare R2.

# Cloudflare R2 example
S3_ENDPOINT_URL='https://account-id.r2.cloudflarestorage.com'

S3_STORAGE_EXPORTS_BUCKET

string

S3 bucket name for snapshot exports.

S3_STORAGE_EXPORTS_BUCKET='convex-snapshot-exports'

S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET

string

S3 bucket name for snapshot imports.

S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET='convex-snapshot-imports'

S3_STORAGE_MODULES_BUCKET

string

S3 bucket name for function modules.

S3_STORAGE_MODULES_BUCKET='convex-modules'

S3_STORAGE_FILES_BUCKET

string

S3 bucket name for user files.

S3_STORAGE_FILES_BUCKET='convex-user-files'

S3_STORAGE_SEARCH_BUCKET

string

S3 bucket name for search indexes.

S3_STORAGE_SEARCH_BUCKET='convex-search-indexes'

AWS_S3_FORCE_PATH_STYLE

boolean

Force path-style S3 URLs instead of virtual-hosted style. Required for some S3-compatible services.

AWS_S3_DISABLE_SSE

boolean

Disable server-side encryption for S3 objects.

AWS_S3_DISABLE_CHECKSUMS

boolean

Disable checksums for S3 operations.

Performance tuning

Concurrency limits

APPLICATION_MAX_CONCURRENT_QUERIES

number

default:"16"

Maximum concurrent queries allowed.

APPLICATION_MAX_CONCURRENT_QUERIES=32

Increasing concurrency increases system load. Monitor your system and tune based on your hardware and workload.

APPLICATION_MAX_CONCURRENT_MUTATIONS

number

default:"16"

Maximum concurrent mutations allowed.

APPLICATION_MAX_CONCURRENT_MUTATIONS=32

APPLICATION_MAX_CONCURRENT_NODE_ACTIONS

number

default:"16"

Maximum concurrent Node.js actions allowed.

APPLICATION_MAX_CONCURRENT_NODE_ACTIONS=32

APPLICATION_MAX_CONCURRENT_V8_ACTIONS

number

default:"16"

Maximum concurrent V8 actions allowed.

APPLICATION_MAX_CONCURRENT_V8_ACTIONS=32

Timeout configuration

ACTIONS_USER_TIMEOUT_SECS

number

Timeout in seconds for action execution.

HTTP_SERVER_TIMEOUT_SECONDS

number

HTTP server timeout in seconds.

Data retention

DOCUMENT_RETENTION_DELAY

number

default:"172800"

Document retention delay in seconds. Default is 2 days (172800 seconds) for self-hosted deployments.

# Keep documents for 7 days
DOCUMENT_RETENTION_DELAY=604800

Logging and monitoring

RUST_LOG

string

default:"info"

Log level for the backend. Options: error, warn, info, debug, trace.

RUST_LOG='debug'

RUST_BACKTRACE

string

Enable Rust backtraces for debugging.

RUST_BACKTRACE='1'

REDACT_LOGS_TO_CLIENT

boolean

default:"false"

Redact log information to prevent leaking PII.

REDACT_LOGS_TO_CLIENT=true

Cloud-hosted Convex automatically redacts logs. Enable this for similar behavior in self-hosted deployments.

DISABLE_BEACON

boolean

default:"false"

Disable the anonymous usage beacon.

DISABLE_BEACON=true

Self-hosted builds include a beacon to help Convex understand usage. The information is anonymous and minimal.

Dashboard configuration

NEXT_PUBLIC_LOAD_MONACO_INTERNALLY

boolean

default:"false"

Load Monaco editor from local assets instead of CDN.

NEXT_PUBLIC_LOAD_MONACO_INTERNALLY=true

Version configuration

CONVEX_RELEASE_VERSION_DEV

string

Override the Convex release version for development.

Example configurations

Local development

.env

PORT=3210
SITE_PROXY_PORT=3211
DASHBOARD_PORT=6791
RUST_LOG=debug

Production with PostgreSQL and S3

.env

# URLs
CONVEX_CLOUD_ORIGIN='https://api.my-domain.com'
CONVEX_SITE_ORIGIN='https://my-domain.com'
NEXT_PUBLIC_DEPLOYMENT_URL='https://api.my-domain.com'

# Database
POSTGRES_URL='postgresql://user:[email protected]'
INSTANCE_NAME='my-production-instance'

# S3 Storage
AWS_REGION='us-east-1'
AWS_ACCESS_KEY_ID='AKIAIOSFODNN7EXAMPLE'
AWS_SECRET_ACCESS_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
S3_STORAGE_EXPORTS_BUCKET='my-convex-exports'
S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET='my-convex-imports'
S3_STORAGE_MODULES_BUCKET='my-convex-modules'
S3_STORAGE_FILES_BUCKET='my-convex-files'
S3_STORAGE_SEARCH_BUCKET='my-convex-search'

# Performance
APPLICATION_MAX_CONCURRENT_QUERIES=32
APPLICATION_MAX_CONCURRENT_MUTATIONS=32

# Security
REDACT_LOGS_TO_CLIENT=true
RUST_LOG=info

Production with Cloudflare R2

.env

# S3-compatible storage (R2)
AWS_REGION='auto'
AWS_ACCESS_KEY_ID='your-r2-access-key-id'
AWS_SECRET_ACCESS_KEY='your-r2-secret-access-key'
S3_ENDPOINT_URL='https://account-id.r2.cloudflarestorage.com'
AWS_S3_FORCE_PATH_STYLE=true

S3_STORAGE_EXPORTS_BUCKET='convex-exports'
S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET='convex-imports'
S3_STORAGE_MODULES_BUCKET='convex-modules'
S3_STORAGE_FILES_BUCKET='convex-files'
S3_STORAGE_SEARCH_BUCKET='convex-search'

Advanced tuning

For detailed configuration options beyond the commonly used variables, see the knobs.rs source file. These knobs are configurable via environment variables but require careful tuning based on your specific workload and hardware.

Advanced knobs can significantly impact performance. Only adjust these if you understand the implications and have profiled your workload.

Getting Started

Core Concepts

Backend Features

Client SDKs

Self-Hosting

Development

Environment variables

Core configuration

Instance configuration

URL configuration

Port configuration

Database configuration

S3 storage configuration

Performance tuning

Concurrency limits

Timeout configuration

Data retention

Logging and monitoring

Dashboard configuration

Version configuration

Example configurations

Local development

Production with PostgreSQL and S3

Production with Cloudflare R2

Advanced tuning

Next steps

Database setup

Storage

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Backend Features

Client SDKs

Self-Hosting

Development

​Environment variables

​Core configuration

​Instance configuration

​URL configuration

​Port configuration

​Database configuration

​S3 storage configuration

​Performance tuning

​Concurrency limits

​Timeout configuration

​Data retention

​Logging and monitoring

​Dashboard configuration

​Version configuration

​Example configurations

​Local development

​Production with PostgreSQL and S3

​Production with Cloudflare R2

​Advanced tuning

​Next steps

Database setup

Storage

Build docs developers (and LLMs) love

Environment variables

Core configuration

Instance configuration

URL configuration

Port configuration

Database configuration

S3 storage configuration

Performance tuning

Concurrency limits

Timeout configuration

Data retention

Logging and monitoring

Dashboard configuration

Version configuration

Example configurations

Local development

Production with PostgreSQL and S3

Production with Cloudflare R2

Advanced tuning

Next steps