Environment Variables

Environment variables allow you to configure your applications without modifying code. Dokploy provides secure management of runtime variables, build arguments, and build secrets.

Environment Variable Types

Dokploy supports three types of variables:

Environment Variables

Runtime configuration available in running containers

Build Arguments

Variables used during Docker image build

Build Secrets

Sensitive build-time data not persisted in images

Environment Variables

Runtime variables available to your application containers.

Configuring Environment Variables

Navigate to Environment

Open your application and go to the “Environment” tab.

Add Variables

Enter variables in KEY=value format (one per line):

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://user:pass@db:5432/mydb
REDIS_URL=redis://redis:6379
API_KEY=abc123xyz789
LOG_LEVEL=info

Save Configuration

Click “Save Environment” to persist changes.

Apply Changes

Redeploy or restart the application to apply new variables:

Restart: Quick update (uses existing image)
Redeploy: Full rebuild with new variables

Variable Formats

Simple Values
URLs & Connections
Multi-line Values
Special Characters

NODE_ENV=production
PORT=3000
ENABLE_CORS=true
MAX_CONNECTIONS=100

DATABASE_URL=postgresql://user:password@hostname:5432/database
REDIS_URL=redis://:password@redis:6379/0
MONGODB_URI=mongodb://user:pass@mongo:27017/db?authSource=admin
API_ENDPOINT=https://api.example.com/v1

Use \n for newlines:

PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----"

Or use quotes for multi-line:

CONFIG="{
  \"option1\": \"value1\",
  \"option2\": \"value2\"
}"

Use quotes for values with special characters:

PASSWORD="p@ssw0rd!#$%"
WEBHOOK_URL="https://example.com/hook?token=abc&secret=xyz"
JSON_CONFIG='{"key": "value with spaces"}'

Project-Level Environment Variables

Define variables shared across all services in a project:

Navigate to Project Settings

Open your project settings.

Configure Project Variables

# Available to ALL services in this project
REGION=us-east-1
ENVIRONMENT=production
LOG_LEVEL=info
SENTRY_DSN=https://abc@sentry.io/123

Service-Level Override

Service-specific variables override project variables:

# Project level
LOG_LEVEL=info

# Service level (overrides project)
LOG_LEVEL=debug

# Result in service container
LOG_LEVEL=debug ✅

Project variables are merged with service variables. Service variables take precedence.

Environment File Generation

Control whether Dokploy creates a .env file in your container:

Enabled (Default)
Disabled

Create .env file: true ✅

Dokploy creates /app/.env with:

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://...

Your application can load it:

// Node.js
require('dotenv').config();

// Python
from dotenv import load_dotenv
load_dotenv()

Create .env file: false

Variables are only available as process environment variables:

// Access via process.env
const port = process.env.PORT;

Disable if your application doesn’t use .env files or if you want environment variables only.

Build Arguments

Variables available during Docker image build process.

Configuring Build Arguments

# Build Arguments (one per line)
NODE_ENV=production
BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
VERSION=1.2.3
API_URL=https://api.production.com
ENABLE_SOURCEMAPS=false

Using in Dockerfile

# Declare arguments
ARG NODE_ENV
ARG BUILD_DATE
ARG VERSION
ARG API_URL

FROM node:18-alpine

# Use during build
RUN echo "Building version ${VERSION} at ${BUILD_DATE}"

# Set as environment variables (optional)
ENV NODE_ENV=${NODE_ENV}
ENV NEXT_PUBLIC_API_URL=${API_URL}

# Use in build commands
RUN if [ "$NODE_ENV" = "production" ]; then \
      npm run build:prod; \
    else \
      npm run build:dev; \
    fi

# Label the image
LABEL version="${VERSION}" \
      build.date="${BUILD_DATE}"

COPY . .

Common Use Cases

Environment-Specific Builds

# Build Arguments
NODE_ENV=production
NEXT_PUBLIC_API_URL=https://api.production.com
NEXT_PUBLIC_SENTRY_DSN=https://abc@sentry.io/123

ARG NODE_ENV
ARG NEXT_PUBLIC_API_URL
ARG NEXT_PUBLIC_SENTRY_DSN

ENV NODE_ENV=${NODE_ENV}
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
ENV NEXT_PUBLIC_SENTRY_DSN=${NEXT_PUBLIC_SENTRY_DSN}

RUN npm run build

Build Optimization

# Build Arguments
ENABLE_SOURCEMAPS=false
MINIFY=true
OPTIMIZE_IMAGES=true

ARG ENABLE_SOURCEMAPS
ARG MINIFY

RUN npm run build -- \
  --sourcemaps=${ENABLE_SOURCEMAPS} \
  --minify=${MINIFY}

Version Tagging

# Build Arguments
VERSION=1.2.3
GIT_COMMIT=abc123
BUILD_DATE=2024-01-15T10:30:00Z

ARG VERSION
ARG GIT_COMMIT
ARG BUILD_DATE

LABEL app.version="${VERSION}" \
      app.commit="${GIT_COMMIT}" \
      app.build-date="${BUILD_DATE}"

# Embed in application
RUN echo "{\"version\":\"${VERSION}\",\"commit\":\"${GIT_COMMIT}\"}" > /app/version.json

Build arguments are visible in the image history. Don’t use them for secrets.

docker history myapp:latest
# Build arguments are visible here! ⚠️

Build Secrets

Secure way to pass sensitive data during builds without persisting in the image.

Configuring Build Secrets

# Build Secrets (one per line)
NPM_TOKEN=npm_abc123xyz789
GITHUB_TOKEN=ghp_xyz789abc456
PIP_INDEX_URL=https://user:pass@pypi.company.com/simple
COMPOSER_AUTH={"github-oauth": {"github.com": "token123"}}

Using in Dockerfile

NPM Private Packages
Private Git Repositories
Private Python Packages
Multiple Secrets

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install with secret NPM token
RUN --mount=type=secret,id=NPM_TOKEN \
    NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) && \
    echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && \
    npm install && \
    rm .npmrc

COPY . .
RUN npm run build

The secret is mounted during build but NOT stored in any image layer.

FROM golang:1.21-alpine

WORKDIR /app

# Configure git with secret token
RUN --mount=type=secret,id=GITHUB_TOKEN \
    git config --global url."https://$(cat /run/secrets/GITHUB_TOKEN)@github.com/".insteadOf "https://github.com/"

# Download private dependencies
COPY go.mod go.sum ./
RUN go mod download

# Clear git config (remove token)
RUN git config --global --unset url."https://github.com/".insteadOf

COPY . .
RUN go build -o app

FROM python:3.11-slim

WORKDIR /app

# Install from private PyPI
RUN --mount=type=secret,id=PIP_INDEX_URL \
    PIP_INDEX_URL=$(cat /run/secrets/PIP_INDEX_URL) && \
    pip install --index-url ${PIP_INDEX_URL} -r requirements.txt

COPY . .

FROM node:18-alpine

WORKDIR /app

# Use multiple secrets
RUN --mount=type=secret,id=NPM_TOKEN \
    --mount=type=secret,id=GITHUB_TOKEN \
    NPM_TOKEN=$(cat /run/secrets/NPM_TOKEN) && \
    GITHUB_TOKEN=$(cat /run/secrets/GITHUB_TOKEN) && \
    echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc && \
    git config --global url."https://${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/" && \
    npm install && \
    rm .npmrc && \
    git config --global --unset url."https://github.com/".insteadOf

COPY . .
RUN npm run build

Build Secrets vs Build Arguments

Build Secrets ✅
Build Arguments ⚠️

When to use:

API tokens
Registry credentials
SSH keys
Private package tokens

Security:

✅ Not stored in image layers
✅ Not visible in docker history
✅ Automatically cleaned up
✅ Safe for sensitive data

Example:

RUN --mount=type=secret,id=NPM_TOKEN \
    npm install

When to use:

Build configuration
Version numbers
Feature flags
Public URLs

Security:

❌ Stored in image layers
❌ Visible in docker history
❌ Persisted in final image
⚠️ NOT safe for secrets

Example:

ARG VERSION=1.0.0
LABEL version="${VERSION}"

Preview-Specific Variables

Configure environment variables specifically for preview deployments:

Preview Environment
Preview Build Args
Preview Build Secrets

# Preview Environment Variables
NODE_ENV=preview
DATABASE_URL=postgresql://preview_user:pass@db:5432/preview_db
ENABLE_DEBUG=true
DISABLE_ANALYTICS=true
API_URL=https://${DOKPLOY_DEPLOY_URL}/api

${DOKPLOY_DEPLOY_URL} is automatically replaced with the preview URL.

# Preview Build Arguments
NODE_ENV=preview
NEXT_PUBLIC_API_URL=https://${DOKPLOY_DEPLOY_URL}/api
NEXT_PUBLIC_ENVIRONMENT=preview
ENABLE_DEBUGGING=true

# Preview Build Secrets (separate credentials)
NPM_TOKEN=${PREVIEW_NPM_TOKEN}
SENTRY_AUTH_TOKEN=${PREVIEW_SENTRY_TOKEN}

Variable Precedence

When the same variable is defined in multiple places:

1. Service Environment Variables (highest priority)
   ↓
2. Preview Environment Variables (for preview deployments)
   ↓
3. Project Environment Variables
   ↓
4. System Defaults (lowest priority)

Example:

# Project level
LOG_LEVEL=info
DATABASE_URL=postgresql://prod_db

# Service level
LOG_LEVEL=debug

# Result in container
LOG_LEVEL=debug          ✅ (service overrides project)
DATABASE_URL=postgresql://prod_db  ✅ (from project)

Security Best Practices

Use Build Secrets

For sensitive build-time data:

RUN --mount=type=secret,id=TOKEN

Avoid Hardcoding

Never commit secrets to code:

❌ API_KEY="abc123" in code
✅ API_KEY in environment

Rotate Credentials

Regularly update sensitive values:

Generate new token
Update in Dokploy
Redeploy services
Revoke old token

Limit Access

Restrict who can view/edit variables:

- Role-based access control
- Audit logs
- Member permissions

Accessing Variables in Applications

Node.js
Python
Go
PHP

// Access environment variables
const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY;

// Using dotenv (if .env file created)
require('dotenv').config();
console.log(process.env.NODE_ENV);

import os
from dotenv import load_dotenv

# Load from .env file (if created)
load_dotenv()

# Access variables
port = int(os.getenv('PORT', 8000))
db_url = os.environ['DATABASE_URL']
api_key = os.getenv('API_KEY')

package main

import (
    "os"
    "github.com/joho/godotenv"
)

func main() {
    // Load .env file (if created)
    godotenv.Load()

    // Access variables
    port := os.Getenv("PORT")
    dbURL := os.Getenv("DATABASE_URL")
    apiKey := os.Getenv("API_KEY")
}

<?php
// Load .env file (if using vlucas/phpdotenv)
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

// Access variables
$port = $_ENV['PORT'] ?? 8080;
$dbUrl = $_ENV['DATABASE_URL'];
$apiKey = getenv('API_KEY');

Troubleshooting

Variable Not Available in Container

Check Variable Name

# Verify exact name (case-sensitive)
DATABASE_URL ✅
database_url ❌

Restart/Redeploy

Changes require:
- Restart (quick, uses existing image)
- Redeploy (full rebuild)

Verify in Container

# Access container terminal
docker exec -it myapp sh

# List all environment variables
env | grep DATABASE_URL

# Check .env file (if created)
cat .env

Build Failing with Secrets

Error: secret required but no secret provider

Solution:
1. Verify build secrets are configured in Dokploy
2. Check secret IDs match Dockerfile:
   
   Dokploy: NPM_TOKEN=abc123
   Dockerfile: --mount=type=secret,id=NPM_TOKEN ✅
   
3. Ensure using BuildKit:
   export DOCKER_BUILDKIT=1

Special Characters Breaking Variables

# Problem
PASSWORD=p@ss$word  # $ interpreted as variable

# Solution: Use quotes
PASSWORD="p@ss$word"  ✅

# Or escape special characters
PASSWORD=p@ss\$word  ✅

Getting Started

Deployment

Databases

Infrastructure

Advanced

Environment Variables

Environment Variable Types

Environment Variables

Build Arguments

Build Secrets

Environment Variables

Configuring Environment Variables

Variable Formats

Project-Level Environment Variables

Environment File Generation

Build Arguments

Configuring Build Arguments

Using in Dockerfile

Common Use Cases

Build Secrets

Configuring Build Secrets

Using in Dockerfile

Build Secrets vs Build Arguments

Preview-Specific Variables

Variable Precedence

Security Best Practices

Use Build Secrets

Avoid Hardcoding

Rotate Credentials

Limit Access

Accessing Variables in Applications

Troubleshooting

Variable Not Available in Container

Build Failing with Secrets

Special Characters Breaking Variables

Next Steps

Applications

Rollbacks

Getting Started

Deployment

Databases

Infrastructure

Advanced

Documentation Index

​Environment Variable Types

Environment Variables

Build Arguments

Build Secrets

​Environment Variables

​Configuring Environment Variables

​Variable Formats

​Project-Level Environment Variables

​Environment File Generation

​Build Arguments

​Configuring Build Arguments

​Using in Dockerfile

​Common Use Cases

​Build Secrets

​Configuring Build Secrets

​Using in Dockerfile

​Build Secrets vs Build Arguments

​Preview-Specific Variables

​Variable Precedence

​Security Best Practices

Use Build Secrets

Avoid Hardcoding

Rotate Credentials

Limit Access

​Accessing Variables in Applications

​Troubleshooting

​Variable Not Available in Container

​Build Failing with Secrets

​Special Characters Breaking Variables

​Next Steps

Applications

Rollbacks

Environment Variable Types

Environment Variables

Configuring Environment Variables

Variable Formats

Project-Level Environment Variables

Environment File Generation

Build Arguments

Configuring Build Arguments

Using in Dockerfile

Common Use Cases

Build Secrets

Configuring Build Secrets

Using in Dockerfile

Build Secrets vs Build Arguments

Preview-Specific Variables

Variable Precedence

Security Best Practices

Accessing Variables in Applications

Troubleshooting

Variable Not Available in Container

Build Failing with Secrets

Special Characters Breaking Variables

Next Steps