> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/get-convex/convex-backend/llms.txt > Use this file to discover all available pages before exploring further. # 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 Name of your Convex instance. This determines the database name (with `-` replaced by `_`). Secret key for your instance. Keep this very safe and only accessible from the backend. Required when running the binary directly. ### URL configuration URL of the Convex API as accessed by clients and the frontend. ```bash theme={null} CONVEX_CLOUD_ORIGIN='https://api.my-domain.com' ``` URL of Convex HTTP actions as accessed by clients and the frontend. ```bash theme={null} CONVEX_SITE_ORIGIN='https://my-domain.com' ``` URL of the Convex API as accessed by the dashboard (browser). ```bash theme={null} NEXT_PUBLIC_DEPLOYMENT_URL='https://api.my-domain.com' ``` ### Port configuration Port for the Convex backend API. Port for HTTP actions. Port for the dashboard web interface. ## Database configuration Generic database connection string. For specific databases, use `POSTGRES_URL` or `MYSQL_URL` instead. PostgreSQL connection string without database name and query parameters. ```bash theme={null} POSTGRES_URL='postgresql://user:password@host.neon.tech' ``` The backend will connect to a database named after your instance (e.g., `convex_self_hosted`). MySQL connection string without database name and query parameters. ```bash theme={null} MYSQL_URL='mysql://user:password@aws.connect.psdb.cloud' ``` Disable SSL requirement for database connections. Useful for local development. Only set this to `true` for local development. Production deployments should use SSL. ```bash theme={null} DO_NOT_REQUIRE_SSL=1 ``` ## S3 storage configuration AWS region for S3 buckets. ```bash theme={null} AWS_REGION='us-east-1' ``` AWS access key ID for S3 authentication. AWS secret access key for S3 authentication. Never commit AWS credentials to source control. Use environment variables or secrets management. AWS session token for temporary credentials. Custom S3 endpoint URL. Required for S3-compatible services like Cloudflare R2. ```bash theme={null} # Cloudflare R2 example S3_ENDPOINT_URL='https://account-id.r2.cloudflarestorage.com' ``` S3 bucket name for snapshot exports. ```bash theme={null} S3_STORAGE_EXPORTS_BUCKET='convex-snapshot-exports' ``` S3 bucket name for snapshot imports. ```bash theme={null} S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET='convex-snapshot-imports' ``` S3 bucket name for function modules. ```bash theme={null} S3_STORAGE_MODULES_BUCKET='convex-modules' ``` S3 bucket name for user files. ```bash theme={null} S3_STORAGE_FILES_BUCKET='convex-user-files' ``` S3 bucket name for search indexes. ```bash theme={null} S3_STORAGE_SEARCH_BUCKET='convex-search-indexes' ``` Force path-style S3 URLs instead of virtual-hosted style. Required for some S3-compatible services. Disable server-side encryption for S3 objects. Disable checksums for S3 operations. ## Performance tuning ### Concurrency limits Maximum concurrent queries allowed. ```bash theme={null} APPLICATION_MAX_CONCURRENT_QUERIES=32 ``` Increasing concurrency increases system load. Monitor your system and tune based on your hardware and workload. Maximum concurrent mutations allowed. ```bash theme={null} APPLICATION_MAX_CONCURRENT_MUTATIONS=32 ``` Maximum concurrent Node.js actions allowed. ```bash theme={null} APPLICATION_MAX_CONCURRENT_NODE_ACTIONS=32 ``` Maximum concurrent V8 actions allowed. ```bash theme={null} APPLICATION_MAX_CONCURRENT_V8_ACTIONS=32 ``` ### Timeout configuration Timeout in seconds for action execution. HTTP server timeout in seconds. ### Data retention Document retention delay in seconds. Default is 2 days (172800 seconds) for self-hosted deployments. ```bash theme={null} # Keep documents for 7 days DOCUMENT_RETENTION_DELAY=604800 ``` ## Logging and monitoring Log level for the backend. Options: `error`, `warn`, `info`, `debug`, `trace`. ```bash theme={null} RUST_LOG='debug' ``` Enable Rust backtraces for debugging. ```bash theme={null} RUST_BACKTRACE='1' ``` Redact log information to prevent leaking PII. ```bash theme={null} REDACT_LOGS_TO_CLIENT=true ``` Cloud-hosted Convex automatically redacts logs. Enable this for similar behavior in self-hosted deployments. Disable the anonymous usage beacon. ```bash theme={null} DISABLE_BEACON=true ``` Self-hosted builds include a beacon to help Convex understand usage. The information is anonymous and minimal. ## Dashboard configuration Load Monaco editor from local assets instead of CDN. ```bash theme={null} NEXT_PUBLIC_LOAD_MONACO_INTERNALLY=true ``` ## Version configuration Override the Convex release version for development. ## Example configurations ### Local development ```bash .env theme={null} PORT=3210 SITE_PROXY_PORT=3211 DASHBOARD_PORT=6791 RUST_LOG=debug ``` ### Production with PostgreSQL and S3 ```bash .env theme={null} # 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:password@db.region.provider.com' 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 ```bash .env theme={null} # 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](https://github.com/get-convex/convex-backend/blob/main/crates/common/src/knobs.rs). 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 Connect to PostgreSQL or MySQL Configure S3-compatible storage