Environment Variables

Overview

Environment variables are key-value pairs that configure your applications at runtime. Qovery provides comprehensive variable management with support for secrets, multiple scopes, interpolation, and file-based variables.

Variable Types

Qovery supports two types of environment variables:

Key/Value Variables

Standard environment variables accessible in your application:

NODE_ENV=production
API_URL=https://api.example.com
MAX_CONNECTIONS=100

In Application Code:

const nodeEnv = process.env.NODE_ENV;
const apiUrl = process.env.API_URL;

Variable as File

Store configuration files that are written to the filesystem at a specific path. The value is stored at the specified file path and accessible for applications or frameworks requiring file-based configuration. Configuration:

Key: Variable name
Value: File content
Path: Absolute path where file will be created (e.g., /etc/config/app.yaml)

Secrets

Secrets are encrypted variables for sensitive data. They are encrypted at rest and in transit, and cannot be retrieved through the API. When to Use Secrets:

Database passwords
API keys and tokens
OAuth credentials
Private keys and certificates
Any sensitive authentication data

Always mark sensitive data as secrets. Secret values cannot be viewed in the console once created - you can only update or delete them.

Variable Scopes

Environment variables can be defined at three different scopes:

Project Scope

Available to: All environments and services within the project Use Cases: Organization-wide settings, shared API keys, common configuration

COMPANY_NAME=Acme Corp
SUPPORT_EMAIL=[email protected]
CDN_URL=https://cdn.acme.com

Environment Scope

Available to: All services within a specific environment Use Cases: Environment-specific configuration, shared database credentials, feature flags

ENVIRONMENT=production
API_URL=https://api.production.com
ENABLE_DEBUG=false

Service Scope

Available to: One specific service (application, job, database, etc.) Use Cases: Service-specific configuration, application-unique settings

PORT=8080
WORKERS=4
RATE_LIMIT=1000

Scope Hierarchy

Variables defined at narrower scopes override those at broader scopes:

Service Scope (highest priority)
    ↓ overrides
Environment Scope
    ↓ overrides
Project Scope (lowest priority)

Built-in Variables

Qovery automatically injects built-in variables for service interconnection and system information.

System Variables

# Project and Environment
QOVERY_PROJECT_ID=<uuid>
QOVERY_ENVIRONMENT_ID=<uuid>
QOVERY_ENVIRONMENT_NAME=production

# Service Information
QOVERY_APPLICATION_ID=<uuid>
QOVERY_APPLICATION_NAME=my-api

# Infrastructure
QOVERY_CLOUD_PROVIDER=AWS
QOVERY_CLOUD_PROVIDER_REGION=us-east-1

Database Connection Variables

For each database, Qovery creates connection variables using the pattern: QOVERY_DATABASE_{DATABASE_NAME}_{PROPERTY} Example - PostgreSQL Database “main-db”:

QOVERY_DATABASE_MAIN_DB_HOST=postgres-z1a2b3c4.internal
QOVERY_DATABASE_MAIN_DB_PORT=5432
QOVERY_DATABASE_MAIN_DB_USERNAME=superuser
QOVERY_DATABASE_MAIN_DB_PASSWORD=<secret>
QOVERY_DATABASE_MAIN_DB_DATABASE=postgres
QOVERY_DATABASE_MAIN_DB_CONNECTION_URI=postgresql://superuser:***@postgres-z1a2b3c4.internal:5432/postgres

Application Connection Variables

Connect to other applications using the pattern: QOVERY_APPLICATION_{APP_NAME}_{PROPERTY}

QOVERY_APPLICATION_FRONTEND_HOST_INTERNAL=frontend-z1a2b3c4.internal
QOVERY_APPLICATION_FRONTEND_PORT=3000
QOVERY_APPLICATION_API_HOST_INTERNAL=api-z1a2b3c4.internal
QOVERY_APPLICATION_API_PORT=8080

Built-in variables are read-only and automatically managed by Qovery. Variable names are generated from service names with underscores replacing hyphens and converted to uppercase.

Creating Variables

Navigate to Service

Select your application, job, or container from the environment

Open Variables Section

Click on Environment Variables in the service menu

Add Variable

Click Add Variable and configure:

Scope: Project, Environment, or Service level
Key: Variable name
Value: Variable value or file content
Type: Variable or Secret
Variable Type: Standard or File (specify path if file)

Save and Redeploy

Save the variable and redeploy services to apply changes

Variable Naming Rules

Allowed:

Alphanumeric characters (A-Z, 0-9)
Underscores (_)
Must start with a letter
Uppercase recommended

Not Allowed:

Cannot start with QOVERY_ (reserved for built-in variables)
Cannot start with __ (double underscore)
No hyphens or special characters
No spaces

Editing and Deleting Variables

Editing

Locate variable in Environment Variables section
Click edit icon
Update value or settings
Save and redeploy

For secrets, you cannot view the current value. You can only set a new value for security reasons.

Deleting

Select variable to remove
Click delete icon and confirm
Redeploy services

Variable Interpolation

Reference other variables within variable values using {{VARIABLE_NAME}} syntax.

Basic Interpolation

# Define base variables
DATABASE_HOST=postgres.internal
DATABASE_PORT=5432
DATABASE_NAME=myapp

# Compose connection string
DATABASE_URL={{DATABASE_HOST}}:{{DATABASE_PORT}}/{{DATABASE_NAME}}
# Result: postgres.internal:5432/myapp

With Built-in Variables

# Use Qovery built-in variables
MY_DATABASE_URL=postgresql://{{QOVERY_DATABASE_MAIN_DB_HOST}}:{{QOVERY_DATABASE_MAIN_DB_PORT}}/{{QOVERY_DATABASE_MAIN_DB_DATABASE}}

# Compose service URLs
BACKEND_API={{QOVERY_APPLICATION_API_HOST_INTERNAL}}:{{QOVERY_APPLICATION_API_PORT}}

Aliases

Create aliases to rename built-in variables to match your application’s expected variable names.

Database Aliases

If your application expects specific variable names, create aliases:

# Application expects DATABASE_URL
# Create alias from built-in variable:
DATABASE_URL = {{QOVERY_DATABASE_MAIN_DB_CONNECTION_URI}}

Application Host Aliases

Create friendly names for service communication:

# Simple aliases for services
API_HOST = {{QOVERY_APPLICATION_API_HOST_INTERNAL}}
REDIS_HOST = {{QOVERY_CONTAINER_REDIS_HOST_INTERNAL}}
POSTGRES_HOST = {{QOVERY_DATABASE_MAIN_DB_HOST}}

Overrides

When variables are defined at multiple scopes, narrower scopes override broader ones:

# Project Scope
LOG_LEVEL=warn

# Environment Scope (overrides project)
LOG_LEVEL=info

# Service Scope (overrides environment)
LOG_LEVEL=debug

# Result: Service sees LOG_LEVEL=debug

Import and Export

Import and export variables in bulk using .env file format.

Exporting

Open Environment Variables section
Click Export to download as .env file
Secret values are exported as *** for security

Importing

Prepare .env File

Create a .env file with key-value pairs:

NEW_VAR_1=value1
NEW_VAR_2=value2
FEATURE_FLAG=true

Import File

Click Import and select your .env file

Review Import

Qovery shows which variables will be:

Created (new)
Updated (existing)
Skipped (conflicts)

Confirm

Review and confirm the import

Import Restrictions:

Cannot import built-in variables (starting with QOVERY_)
Cannot overwrite existing secrets (must delete first)
Cannot import variables with invalid names

Existing non-secret variables at the same scope will be updated during import. Use carefully to avoid overwriting configuration.

Service Interconnection

Use environment variables to connect services within your environment.

Database Connection

// Using built-in variables
const { Client } = require('pg');

const client = new Client({
  host: process.env.QOVERY_DATABASE_MAIN_DB_HOST,
  port: process.env.QOVERY_DATABASE_MAIN_DB_PORT,
  database: process.env.QOVERY_DATABASE_MAIN_DB_DATABASE,
  user: process.env.QOVERY_DATABASE_MAIN_DB_USERNAME,
  password: process.env.QOVERY_DATABASE_MAIN_DB_PASSWORD,
});

// Or use connection URI
const client = new Client({
  connectionString: process.env.QOVERY_DATABASE_MAIN_DB_CONNECTION_URI
});

Application-to-Application Communication

// Internal service communication
const backendUrl = `http://${process.env.QOVERY_APPLICATION_API_HOST_INTERNAL}:${process.env.QOVERY_APPLICATION_API_PORT}`;

const response = await fetch(`${backendUrl}/api/data`);

Best Practices

Security: Always mark sensitive data as secrets
Naming: Use UPPER_CASE_WITH_UNDERSCORES and descriptive names
Organization: Use appropriate scopes (Project for shared, Environment for env-specific, Service for unique)
Rotation: Periodically rotate sensitive credentials
Documentation: Document variable purposes and expected values
Cleanup: Remove unused variables regularly

Applications

Configure applications with environment variables

Databases

Connect databases using built-in variables

Deploy Application

Deploy with configured variables

Connect Database

Use environment variables for database connections

Overview

Account & Organization

Clusters & Cloud

Source Control

Projects & Environments

Services

Deployment & CI/CD

Secrets & Monitoring

Notifications

Networking & Advanced

​Overview

​Variable Types

​Key/Value Variables

​Variable as File

​Secrets

​Variable Scopes

​Project Scope

​Environment Scope

​Service Scope

​Scope Hierarchy

​Built-in Variables

​System Variables

​Database Connection Variables

​Application Connection Variables

​Creating Variables

​Variable Naming Rules

​Editing and Deleting Variables

​Editing

​Deleting

​Variable Interpolation

​Basic Interpolation

​With Built-in Variables

​Aliases

​Database Aliases

​Application Host Aliases

​Overrides

​Import and Export

​Exporting

​Importing

​Service Interconnection

​Database Connection

​Application-to-Application Communication

​Best Practices

​Related Resources

Applications

Databases

Deploy Application

Connect Database

Overview

Variable Types

Key/Value Variables

Variable as File

Secrets

Variable Scopes

Project Scope

Environment Scope

Service Scope

Scope Hierarchy

Built-in Variables

System Variables

Database Connection Variables

Application Connection Variables

Creating Variables

Variable Naming Rules

Editing and Deleting Variables

Editing

Deleting

Variable Interpolation

Basic Interpolation

With Built-in Variables

Aliases

Database Aliases

Application Host Aliases

Overrides

Import and Export

Exporting

Importing

Service Interconnection

Database Connection

Application-to-Application Communication

Best Practices

Related Resources