How to Manage Environment Variables in Dokploy

Dokploy has emerged as a powerful self-hosted alternative to platforms like Vercel and Heroku. For teams who want control over their infrastructure while maintaining a modern deployment experience, Dokploy provides a clean solution with built-in environment variable management. This guide covers everything from basic variable setup to scaling configuration management as your team grows.

What is Dokploy?

Dokploy is an open-source, self-hosted Platform as a Service (PaaS) that simplifies deploying applications on your own infrastructure. It supports Docker-based deployments, automatic SSL certificates, and built-in environment variable management - all through a clean web interface.

For teams concerned about vendor lock-in, data sovereignty, or compliance requirements, Dokploy provides the deployment experience of managed platforms while keeping everything under your control.

Dokploy's Environment Variable System

Dokploy provides environment variable management at multiple levels, giving you flexibility in how you organize your configuration.

Project-Level vs. Service-Level Variables

In Dokploy, you can define environment variables at two levels:

• Service-level variables - Specific to a single application or service
• Shared variables - Available across multiple services in a project

This hierarchy allows you to define common configuration (like database URLs) once and reference them across services, while still supporting service-specific overrides.

Adding Environment Variables in Dokploy

To add environment variables to a Dokploy application:

1. Navigate to your application in the Dokploy dashboard
2. Go to the Environment tab
3. Add your variables in KEY=VALUE format
4. Save and redeploy

# Example configuration
DATABASE_URL=postgresql://user:pass@db.internal:5432/myapp
REDIS_URL=redis://redis.internal:6379
API_SECRET_KEY=your-secret-key-here
NODE_ENV=production

Docker Compose Integration

For applications using Docker Compose, Dokploy can read environment variables from your compose file:

# docker-compose.yml
services:
  web:
    image: myapp:latest
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - API_SECRET_KEY=${API_SECRET_KEY}

Variables defined in the Dokploy dashboard are injected into your containers at runtime.

Challenges with Self-Hosted Environment Management

While self-hosting gives you control, it also introduces challenges that managed platforms handle for you:

1. No Built-in Secret Encryption

Unlike managed platforms, self-hosted solutions often store environment variables in plain text. If someone gains access to your Dokploy instance, they can see all your secrets.

2. Limited Access Control

Dokploy's access control is at the project level. You can't easily restrict who can see specific environment variables while still allowing deployment access.

3. Manual Syncing Across Environments

If you run multiple Dokploy instances (staging, production) or multiple servers, keeping environment variables in sync requires manual effort.

4. Audit Trail Gaps

When configuration changes cause issues, tracing what changed and when can be difficult without proper logging infrastructure.

5. Secret Rotation Complexity

Rotating secrets across multiple services requires updating each one individually and redeploying - risky without proper coordination.

Best Practices for Dokploy Environment Variables

Use Meaningful Variable Naming

Adopt a naming convention that includes context about the variable's purpose and environment:

# Good: Clear, contextual names
DB_PRIMARY_HOST=db-primary.internal
DB_REPLICA_HOST=db-replica.internal
STRIPE_API_KEY_LIVE=sk_live_xxx
SMTP_HOST_INTERNAL=mail.internal

# Avoid: Ambiguous names
HOST=xxx
KEY=xxx

Separate Secrets from Configuration

Distinguish between secrets (credentials, API keys) and configuration (feature flags, URLs):

# Secrets - treat with extra care
DATABASE_PASSWORD=sensitive-password
API_SECRET_KEY=xxx
JWT_SIGNING_KEY=xxx

# Configuration - less sensitive
LOG_LEVEL=info
MAX_UPLOAD_SIZE=10485760
FEATURE_DARK_MODE=true

Document Your Configuration

Maintain a reference document for your team:

## Dokploy Environment Variables

### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| DATABASE_URL | PostgreSQL connection string | postgresql://... |
| REDIS_URL | Redis connection string | redis://... |

### Optional Variables
| Variable | Description | Default |
|----------|-------------|---------|
| LOG_LEVEL | Logging verbosity | info |
| MAX_WORKERS | Worker process count | 4 |

Implement Backup Procedures

Back up your Dokploy configuration regularly. Environment variables are part of your critical infrastructure configuration:

# Export configuration periodically
dokploy export --project myproject > backup-$(date +%Y%m%d).json

Integrating EnvManager with Dokploy

For teams running Dokploy at scale, EnvManager (free tier available, Pro under €10/month) provides the additional capabilities you need. Your infrastructure stays on your servers. EnvManager handles the configuration layer with encrypted storage — your secrets are encrypted at rest via Supabase Vault and pgsodium, and only revealed to authorized team members.

Encrypted Secret Storage

EnvManager encrypts all secrets at rest. Even if your EnvManager database were compromised, your secrets remain protected. Team members can only reveal secrets they have access to.

Role-Based Access Control

Define who can view, edit, or manage specific variables:

• Viewers can see variable names but not secret values
• Editors can modify non-secret variables
• Admins can manage all variables and team access

Comprehensive Audit Logging

Every change in EnvManager is logged with:

• What changed
• Who made the change
• When it happened
• Previous and new values (for non-secrets)

When your staging deploy breaks at 11 PM, the audit log shows exactly who changed what and when — no more guessing or Slack archaeology.

Multi-Environment Support

EnvManager mirrors Dokploy's environment structure. Create development, staging, and production environments, then compare configurations to catch discrepancies before they cause issues.

Team Collaboration

Share environment variables securely with your team through EnvManager's encrypted platform, rather than copying secrets via Slack or email.

Setting Up EnvManager for Dokploy

Here's how to enhance your Dokploy workflow with EnvManager:

1. Create Your Project Structure

In EnvManager, create a project that mirrors your Dokploy setup. Add environments for each deployment target (development, staging, production).

2. Import Existing Variables

Export your current Dokploy environment variables and import them into EnvManager:

# From Dokploy, copy your environment variables
# Then import via EnvManager's dashboard import feature

3. Establish EnvManager as Source of Truth

Going forward, manage all environment variables in EnvManager. When you need to update Dokploy, export from EnvManager.

4. Set Up Access Controls

Invite your team to EnvManager with appropriate roles:

• Developers: Can view and use variables for local development
• DevOps: Can edit variables and manage environments
• Admins: Full access including team management

5. Sync to Dokploy

When deploying or updating configuration:

1. Export the relevant environment from EnvManager
2. Update your Dokploy application's environment variables
3. Trigger a redeployment

Dokploy vs. Other Self-Hosted Options

If you're evaluating self-hosted deployment platforms, here's how Dokploy compares:

For teams choosing between self-hosted options, the environment variable management is similar across platforms. The real differentiator is using a dedicated tool like EnvManager to centralize and secure your configuration.

Security Considerations for Self-Hosted Deployments

Running your own infrastructure means taking responsibility for security:

Secure Your Dokploy Instance

• Use strong authentication for the Dokploy dashboard
• Place Dokploy behind a VPN or restrict access by IP
• Keep Dokploy and its dependencies updated
• Use HTTPS for all dashboard access

Protect Environment Variables

• Don't store environment variables in version control
• Use EnvManager for encrypted secret storage
• Rotate credentials regularly
• Monitor for unauthorized access

Network Security

• Use internal networks for service-to-service communication
• Avoid exposing database ports publicly
• Implement proper firewall rules

Conclusion

Dokploy provides a solid foundation for self-hosted deployments, but managing environment variables at scale requires additional tooling. By combining Dokploy's deployment capabilities with EnvManager's secure configuration management, you get the best of both worlds: infrastructure control and team-friendly secret management.

Whether you're deploying a single application or managing a fleet of microservices, proper environment variable management is essential for security, collaboration, and operational efficiency.

Ready to secure your Dokploy secrets with encrypted storage and audit trails? Start free with EnvManager — no credit card required.

Related Resources

• Environment Variable Best Practices
• Team Management in EnvManager
• Importing Variables from .env Files
• How to Manage Environment Variables in Coolify
• How to Manage Environment Variables in Vercel
• Why .env Files Are a Security Nightmare