Dokploy Integration
Dokploy is a self-hosted platform for deploying and managing applications. The Dokploy integration allows you to automatically sync your environment variables from EnvManager directly to your Dokploy applications, databases, and services, keeping your deployments up-to-date without manual copying.
How It Works
When you connect EnvManager to Dokploy:
- One-time Setup: Connect your Dokploy instance with an API token
- Choose Your Target: Select which Dokploy project and service to sync to
- Map Environments: Choose which EnvManager environment syncs to Dokploy
- Auto-sync or Manual: Variables sync automatically on changes, or manually when you click "Sync Now"
- Audit Trail: View complete sync history with timestamps and status
Before You Begin
To connect Dokploy, you need:
- A self-hosted Dokploy instance - Dokploy must be installed and running (e.g.,
https://dokploy.example.com) - API Token - Generated from your Dokploy dashboard at Settings > Profile > API Keys
- Project Administrator role in EnvManager - Required to connect integrations
- At least one project and service - Created in your Dokploy instance
Dokploy is self-hosted, so you need access to your own Dokploy instance. If you don't have one yet, visit Dokploy's documentation to set one up.
Generating Your Dokploy API Token
Log into Dokploy
Open your Dokploy dashboard in your web browser.
Navigate to Profile Settings
Click your profile icon in the top-right corner, then select Settings > Profile.
Go to API Keys
Click the API Keys tab in the profile settings.
Create New API Key
Click Create API Key and give it a descriptive name like "EnvManager Integration".
Copy the Token
After creation, copy the API token immediately. You won't be able to see it again after closing the dialog.
Security Note: Keep your API token secure. It provides full access to your Dokploy instance. Never commit it to version control or share it publicly.
Connecting Your Dokploy Instance
Open Integration Settings
From your EnvManager dashboard, click Settings in the sidebar, then select Integrations.
Click Connect Dokploy
Find the Dokploy card in the integrations list and click Connect.
Enter Connection Details
Fill in the connection form:
| Field | Description | Example |
|---|---|---|
| Connection Name | A friendly name for this connection | Production Dokploy |
| Instance URL | Your Dokploy instance URL (without trailing slash) | https://dokploy.example.com |
| API Token | The token you generated in Dokploy | dkp_abc123... |
You can also paste just the domain if using the default Dokploy cloud (e.g., app.dokploy.com).
SSL Certificate Options (Self-Signed Only)
If your Dokploy instance uses a self-signed SSL certificate:
- Check the Allow self-signed certificate checkbox
- Optionally paste your CA certificate in PEM format in the text area that appears
Leave this unchecked if you're using a valid SSL certificate from Let's Encrypt or a commercial CA.
Validate Connection
Click Validate Connection. EnvManager will test your credentials and display:
- A success message with your Dokploy account name
- An error message if the connection failed
If you see an SSL error and you're using a self-signed certificate, check the SSL certificate option above.
Save Connection
Once validation succeeds, click Connect to save the connection.
Connected Successfully: Your Dokploy instance is now connected. You can now configure sync targets for your projects.
Configuring Variable Sync
After connecting Dokploy, you need to configure which variables sync to which services.
Navigate to Your Project
Go to the EnvManager project you want to sync from.
Open Configure Sync
In the integrations panel on the project page, find your Dokploy connection and click Configure.
Select Dokploy Project
In the configuration modal, use the dropdown to select which Dokploy project to sync to.
You can use the search box to filter projects if you have many.
Select Service
After selecting a project, choose which service within that project should receive the variables.
The dropdown shows all services in the project with their type in parentheses:
- Application - Web applications and APIs
- Compose - Docker Compose stacks
- Database - Managed databases (PostgreSQL, MySQL, MariaDB, MongoDB, Redis)
Choose Source Environment
Select which EnvManager environment to sync:
- Development - Your local development variables
- Staging - Pre-production testing variables
- Production - Live production variables
Only one EnvManager environment can sync to each Dokploy service.
The environment you select determines which variables are sent to Dokploy. For example, if you select "Production", only variables from your Production environment will sync.
Configure Sync Options
Choose what to sync using the toggle switches:
| Option | Description |
|---|---|
| Auto-sync | Automatically sync when variables change in EnvManager |
| Sync secrets | Include secret variables (they'll be visible in Dokploy dashboard) |
| Sync regular variables | Include non-secret variables |
Recommended settings:
- Enable Auto-sync for seamless updates
- Enable Sync secrets and Sync regular variables to sync all variables
Save Configuration
Click Save Configuration to complete the setup.
Deployment Required: After syncing variables to Dokploy, you may need to redeploy your application for the changes to take effect. Dokploy does not automatically restart applications when environment variables change.
Syncing Variables
Once configured, variables sync automatically or manually depending on your settings.
Automatic Sync
If you enabled Auto-sync, variables sync automatically whenever you:
- Add a new variable
- Update an existing variable
- Delete a variable
The sync happens in the background, and you'll see a toast notification when it completes.
Manual Sync
To manually trigger a sync:
Go to Your Project
Navigate to the EnvManager project with Dokploy configured.
Click Sync Now
In the integrations panel, find your Dokploy connection and click Sync Now.
Wait for Completion
A loading indicator appears while syncing. When complete, you'll see a success or error message.
Viewing Sync History
EnvManager tracks every sync operation for audit and troubleshooting purposes.
Open Sync History
In the integrations panel on your project page, click View History next to your Dokploy connection.
Review Sync Entries
The sync history shows:
- Timestamp - When the sync occurred
- Trigger Type - Whether it was automatic or manual
- Status - Success, partial, or failed
- Items Synced - Number of variables and secrets synced
View Sync Details
Click any history entry to expand it and see:
- Breakdown of variables vs. secrets synced
- List of variable keys that were synced
- Error messages if the sync failed
Entries are grouped by date (Today, Yesterday, or specific date) for easy navigation.
Sync history is retained indefinitely for compliance and audit purposes. You can use it to track when specific variables were deployed.
Understanding Sync Behavior
What Gets Synced
When a sync runs:
- Variable keys and values from the selected EnvManager environment are sent to Dokploy
- Variables are created or updated in Dokploy based on the key name
- Variables removed from EnvManager are not automatically deleted from Dokploy (you must delete them manually in Dokploy)
Secret Handling
When you sync secrets to Dokploy:
- Secret values are decrypted in EnvManager
- Values are sent to Dokploy via encrypted HTTPS
- Secrets become visible as plain text in the Dokploy dashboard
Security Consideration: Secrets synced to Dokploy are stored as regular environment variables and can be viewed by anyone with access to the Dokploy project. Only sync secrets to Dokploy if your team has appropriate access controls in place.
Service Types
Different Dokploy service types handle environment variables differently:
- Applications & Compose - Variables are injected as environment variables at runtime
- Databases - Variables may be used for configuration (check Dokploy documentation for your specific database)
Consult Dokploy's documentation for service-specific behavior.
Tips & Best Practices
Use Descriptive Connection Names
If you have multiple Dokploy instances (e.g., staging and production), use clear connection names:
- "Production Dokploy - AWS"
- "Staging Dokploy - DigitalOcean"
This makes it easier to select the correct instance when configuring projects.
Match Environments Correctly
Be intentional about environment mapping:
- EnvManager Production → Dokploy production service
- EnvManager Staging → Dokploy staging service
- EnvManager Development → Dokploy development service (if applicable)
Avoid accidentally syncing production secrets to a staging service.
Test First
Before enabling auto-sync on production:
- Configure a test project
- Trigger a manual sync
- Verify variables appear correctly in Dokploy
- Test that your application works with the synced variables
Self-Hosted SSL Certificates
If your Dokploy instance uses a self-signed certificate:
- Export your CA certificate in PEM format
- Paste it in the CA Certificate field during connection setup
- Validate the connection to ensure it works
Without the CA certificate, EnvManager cannot verify the SSL connection and will reject it for security.
Redeploy After Sync
Remember to redeploy your Dokploy service after variables sync to pick up the changes. Dokploy does not automatically restart applications when environment variables change.
Troubleshooting
Connection Validation Fails
Problem: "Failed to validate connection" error when connecting.
Solutions:
- Verify your instance URL is correct (no trailing slash)
- Check that your API token is valid and not expired
- Ensure EnvManager can reach your Dokploy instance (no firewall blocking)
- For self-signed certificates, enable the "Allow self-signed certificate" option
SSL Certificate Errors
Problem: "SSL certificate problem: unable to verify" or similar errors.
Solutions:
- If using a self-signed certificate, check the "Allow self-signed certificate" box
- Paste your CA certificate in PEM format in the certificate field
- Verify your certificate is not expired
- Ensure your Dokploy instance has a valid SSL configuration
Projects or Services Not Showing
Problem: Dropdowns are empty when configuring sync target.
Solutions:
- Verify you have at least one project created in Dokploy
- Create at least one service (application, database, etc.) in the project
- Check your API token has permission to list projects
- Refresh the configuration modal to reload the list
Variables Not Appearing in Dokploy
Problem: Sync succeeds, but variables don't appear in Dokploy dashboard.
Solutions:
- Wait a few seconds and refresh the Dokploy page
- Verify you're looking at the correct service in Dokploy
- Check the sync history to confirm which variables were synced
- Ensure "Sync variables" or "Sync secrets" was enabled in configuration
Sync Fails with "403 Forbidden"
Problem: Sync history shows failed status with 403 error.
Solutions:
- Regenerate your Dokploy API token
- Update the connection in EnvManager with the new token
- Verify your token has write permissions for the target project
Application Not Picking Up Variables
Problem: Variables synced successfully, but application still uses old values.
Solutions:
- Redeploy your application in Dokploy to pick up new environment variables
- Check Dokploy logs to see what variables the application received
- Verify the application is configured to read from environment variables
Disconnecting Dokploy
To disconnect your Dokploy integration:
Go to Integration Settings
Navigate to Settings > Integrations in your EnvManager dashboard.
Find Your Dokploy Connection
Locate the Dokploy connection you want to remove.
Click Disconnect
Click the Disconnect button next to the connection name.
Confirm Disconnection
A confirmation dialog appears. Click Disconnect to confirm.
Disconnecting removes the connection and sync configuration from EnvManager. Variables already synced to Dokploy will remain there and must be deleted manually if needed.
Security Considerations
API Token Security
- Store your Dokploy API token securely
- Never commit tokens to version control
- Rotate tokens periodically
- Use separate tokens for different environments if possible
Network Security
- Use HTTPS for your Dokploy instance
- Consider IP whitelisting if EnvManager uses static IPs
- Use firewall rules to restrict access to your Dokploy instance
Secret Visibility
- Secrets synced to Dokploy become visible as plain text
- Ensure appropriate access controls in Dokploy
- Consider which secrets actually need to be synced
Audit and Compliance
- Use sync history to track when secrets were deployed
- Review sync logs regularly for unexpected changes
- Maintain separate Dokploy instances for different security zones
Related Topics
Managing Variables
Learn how to create and organize environment variables.
Roles & Permissions
Understand who can connect integrations and sync variables.
Environments
Learn about Development, Staging, and Production environments.