Environment Variables

Manage environment-level configuration and variables for applications and services

Environments in Dokploy allow you to organize applications and services into logical groups (e.g., production, staging, development) with isolated configuration and environment variables.

Create Environment

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/environment.create \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging",
    "description": "Staging environment for testing",
    "projectId": "project_abc123"
  }'

Request Body

name · string · required

Name of the environment. Must be at least 1 character. Cannot be production (this name is reserved for the default environment).

description · string

Optional description of the environment’s purpose.

projectId · string · required

ID of the project this environment belongs to.

Response

environmentId · string

Unique identifier for the created environment.

name · string

Environment name.

description · string

Environment description.

projectId · string

Associated project ID.

env · string

Environment variables (empty string by default).

isDefault · boolean

Whether this is the default environment.

createdAt · string

ISO 8601 timestamp when the environment was created.

Get Environment

cURL

curl -X GET "https://your-dokploy-instance.com/api/trpc/environment.one?environmentId=env_xyz789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

environmentId · string · required

ID of the environment to retrieve.

Response

Returns the environment object with all associated applications, databases, and compose services. For member users, only services they have access to are included.

environmentId · string

Environment identifier.

name · string

Environment name.

description · string

Environment description.

env · string

Environment variables in KEY=VALUE format (newline-separated).

project · object

Project this environment belongs to.

applications · array

Array of applications in this environment.

postgres · array

Array of PostgreSQL databases in this environment.

mysql · array

Array of MySQL databases in this environment.

mariadb · array

Array of MariaDB databases in this environment.

mongo · array

Array of MongoDB databases in this environment.

redis · array

Array of Redis databases in this environment.

compose · array

Array of compose services in this environment.

Get Environments by Project

cURL

curl -X GET "https://your-dokploy-instance.com/api/trpc/environment.byProjectId?projectId=project_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

projectId · string · required

ID of the project.

Response

Returns an array of environments belonging to the project. For member users, only environments they have access to are included.

Update Environment

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/environment.update \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_xyz789",
    "name": "staging-v2",
    "description": "Updated staging environment",
    "env": "API_KEY=secret\nDEBUG=true"
  }'

Request Body

environmentId · string · required

ID of the environment to update.

name · string

New name for the environment. Cannot rename the default environment.

description · string

Updated description.

env · string

Environment variables in KEY=VALUE format, separated by newlines. These variables are available to all services in the environment.

Example:

DATABASE_URL=postgresql://localhost/mydb
API_KEY=your-api-key
DEBUG=false

projectId · string

Project ID (cannot be changed for existing environments).

Delete Environment

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/environment.remove \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_xyz789"
  }'

Request Body

environmentId · string · required

ID of the environment to delete.

You cannot delete the default environment. All services in the environment must be deleted first.

Duplicate Environment

Create a copy of an existing environment with all its configuration.

cURL

curl -X POST https://your-dokploy-instance.com/api/trpc/environment.duplicate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "env_xyz789",
    "name": "staging-copy",
    "description": "Copy of staging environment"
  }'

Request Body

environmentId · string · required

ID of the environment to duplicate.

name · string · required

Name for the new environment.

description · string

Description for the new environment.

Response

Returns the newly created environment with the same configuration as the source environment.

Environment Variables Best Practices

Environment variables are inherited by all services within an environment. You can also set service-specific variables that override environment-level values.

Variable Format

Environment variables should be in KEY=VALUE format, with one variable per line:

DATABASE_URL=postgresql://user:pass@localhost/db
API_KEY=your-secret-key
NODE_ENV=production
PORT=3000

Security

• Store sensitive values like API keys and passwords in environment variables
• Never commit environment variables to version control
• Use different values for different environments (staging vs production)
• Rotate secrets regularly

Variable Precedence

When the same variable is defined in multiple places:

1. Service-level environment variables (highest priority)
2. Environment-level variables
3. Default values in your application code (lowest priority)