Runtime configuration

Configure environment variables and runtime options for your self-hosted Convex deployment

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:[e-mail]'

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:[e-mail]'

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:[e-mail]'
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.

Next steps

Database setup

Connect to PostgreSQL or MySQL

Storage

Configure S3-compatible storage