Coolify Integration

Coolify is an open-source, self-hosted alternative to platforms like Heroku and Vercel. With EnvManager's Coolify integration, you can securely sync environment variables from EnvManager directly to your Coolify applications and services, maintaining EnvManager as your single source of truth for configuration.

This integration is particularly valuable for teams using self-hosted infrastructure who need centralized configuration management, granular access control, and complete audit trails.

Before You Begin

To connect Coolify to EnvManager, you'll need:

A running Coolify instance - Your self-hosted Coolify installation with an accessible URL
A Coolify API token - Generated from your Coolify dashboard
Project access in EnvManager - Admin or owner role for the project you want to sync
SSL certificate (optional) - If using self-signed certificates, you'll need the CA certificate

Generating a Coolify API Token

To create an API token in Coolify:

Navigate to Security Settings

In your Coolify dashboard, click on your profile menu and select Security.

Go to API Tokens

Click on the API Tokens section.

Create New Token

Click Create New Token, give it a descriptive name (e.g., "EnvManager Integration"), and save the token securely.

Important: Coolify API tokens are only shown once. Copy your token immediately and store it securely. If you lose it, you'll need to generate a new one.

Connecting Your Coolify Instance

Open Integrations

From your project page in EnvManager, click the Integrations tab in the navigation menu.

Add Coolify Connection

Click the Connect Coolify button to open the connection dialog.

Enter Instance Details

Fill in your Coolify instance information:

Field	Description	Example
Connection Name	A friendly name to identify this Coolify instance	`Production Coolify`
Instance URL	Your Coolify installation URL (no trailing slash)	`https://coolify.example.com`
API Token	The token you generated in Coolify	`abcd1234...`

Configure SSL Settings (Optional)

If your Coolify instance uses a self-signed SSL certificate:

Check the Allow self-signed certificate checkbox
Paste your CA certificate in PEM format in the text area that appears:

-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJAKL...
-----END CERTIFICATE-----

Validate Connection

Click Validate Connection to verify that EnvManager can communicate with your Coolify instance. The system will:

Test the connection to your Coolify API
Verify the token is valid
Check SSL certificate validity (if provided)

If validation succeeds, you'll see a green confirmation message.

Complete Connection

Click Connect to save your Coolify connection. Your instance is now ready to sync.

SSL Certificate Tip: If you see an SSL error during validation and you're using a self-signed certificate, enable the "Allow self-signed certificate" option and provide your CA certificate.

Configuring Your Sync

Once connected, you need to configure which Coolify resource to sync to and which environments to include.

Open Sync Configuration

After connecting, click the Configure button next to your Coolify connection in the integrations list.

Select Resource Type

Choose the type of Coolify resource you want to sync to:

Application - A deployed application (most common)
Service - A Docker Compose service

Click the corresponding button to filter available resources. The number in parentheses shows how many of each type are available.

Databases cannot be sync targets. Coolify's API provides no environment variable endpoints for database resources, so EnvManager cannot read, write, or delete variables on them. Only applications and services can be selected. If an older configuration still points at a database, the configuration dialog will ask you to pick a new target before you can save, and syncing to it fails with an explanation.

Choose Your Target Resource

From the dropdown menu, select the specific application or service where you want to sync variables.

You'll see the resource name and additional details:

Applications show their FQDN (fully qualified domain name)
Services are listed by name

Select Environments to Sync

Choose which EnvManager environments to include in the sync. Variables from all selected environments will be merged and sent to Coolify.

For example, if you select both "Production" and "Shared", all variables from both environments will be synced.

If the same variable key exists in multiple selected environments, the environment listed last will take precedence. Plan your environment structure accordingly.

Configure Sync Options

Set how you want variables synced:

Option	Description	When to Use
Include as build variables	Variables available during Docker build	Enable for Next.js, Gatsby, or other build-time configs
Restart after sync	Restarts the Coolify resource after every successful sync so the new values are actually used	Enable unless you deploy on your own schedule
Auto-sync	Automatically sync when variables change in EnvManager	Enable for continuous deployment workflows
Sync secrets	Include variables marked as secrets	Usually enabled, but disable if you prefer manual secret handling
Sync regular variables	Include non-secret variables	Keep enabled unless you only want secrets synced

Save Configuration

Click Save Configuration to complete the setup.

Coolify applies environment variables only on restart. A sync writes the new values into Coolify, but a running container keeps serving the old ones until the resource is restarted or redeployed. Enable Restart after sync to let EnvManager trigger that restart for you, or restart the resource in Coolify yourself after each sync. Every sync result tells you which of the two happened.

What Happens to Deleted Variables

EnvManager remembers which keys it pushed to each Coolify resource. When you delete a variable in EnvManager (or rename it, or change the prefix), the next sync removes the old key from Coolify as well, so stale configuration doesn't linger.

Only keys that EnvManager synced itself are ever deleted. Environment variables you created directly in Coolify - and preview-deployment variables - are never touched.

If a deletion fails (for example Coolify is briefly unreachable), the sync is reported as partial and the key stays on EnvManager's list so the next sync retries it.

Understanding Build Variables vs Runtime Variables

Coolify distinguishes between two types of environment variables:

Runtime Variables

These variables are injected when your container starts. They're the standard way to configure most applications and are available in your running application code.

Use runtime variables for:

Database connection strings
API keys and secrets
Application configuration
Feature flags

Build Variables

When enabled via "Include as build variables", variables are also available during the Docker build process. This is necessary for frameworks that embed configuration at build time.

Use build variables for:

Next.js public environment variables (NEXT_PUBLIC_*)
Gatsby environment variables
Create React App variables (REACT_APP_*)
Build-time feature flags

Security Warning: Build-time variables may be baked into your Docker image layers. Avoid using sensitive secrets as build variables. If you must, ensure proper image access controls are in place.

Syncing Variables

Manual Sync

To sync variables immediately:

Navigate to Integrations

Go to your project's Integrations tab.

Find Your Coolify Connection

Locate your Coolify connection in the list.

Click Sync Now

Click the Sync Now button to push the latest variables to Coolify.

Wait for Completion

The sync process typically takes a few seconds. The confirmation message tells you how many variables were synced, how many stale ones were removed, and either "Restart triggered in Coolify" or "Restart required".

Restart in Coolify (if required)

If the result said a restart is required, go to your Coolify dashboard and restart or redeploy the resource. Turn on Restart after sync in the configuration to skip this step in future.

Automatic Sync

If you enabled Auto-sync in your configuration, EnvManager will automatically sync variables to Coolify whenever you:

Add a new variable
Edit an existing variable
Delete a variable
Change which environments are included

Automatic syncs run in the background and never block your changes from being saved. Successful ones stay quiet; if one fails or only partly succeeds, you get a notification naming the platform so you can open the integration page and look at the sync history.

Unless Restart after sync is enabled, an automatic sync has the same restriction as a manual one: the values sit in Coolify until the resource is restarted.

Viewing Sync History

EnvManager maintains a complete history of all syncs to Coolify.

Open Integrations

Navigate to your project's Integrations tab.

View Sync History

Click View History next to your Coolify connection to see all past syncs.

Review Sync Details

For each sync, you can see:

Timestamp - When the sync occurred
Triggered by - The user who initiated the sync (or "Auto-sync" for automatic syncs)
Status - Whether the sync succeeded, partly succeeded, or failed
Variables synced - Number of variables pushed to Coolify
Variables deleted - Stale keys that were removed from Coolify
Restart - Whether EnvManager triggered a restart afterwards
Environments - Which environments were included

Check for Errors

If a sync failed, click on it to see the error details and troubleshooting guidance.

This audit trail is valuable for debugging configuration issues and maintaining compliance records.

Tips & Best Practices

Coolify Resource Organization

Group related applications: If you have multiple Coolify applications that share configuration, consider:

Using EnvManager's environment structure to share common variables
Creating a "Shared" environment in EnvManager with common values
Syncing the "Shared" environment along with application-specific ones

Build Variable Strategy

Only enable "Include as build variables" when necessary:

Check your framework requirements - Review your application's build process to determine if it needs build-time variables
Minimize build variables - Keep the number of build-time variables small to avoid image bloat
Use runtime when possible - Most secrets and configuration should be runtime variables

Testing Changes

Before syncing to production:

Test in a staging environment first
Use Coolify's preview deployments to verify configuration
Review the sync history to confirm what was sent
Keep a local backup of critical configuration

Security Considerations

Token security: Your Coolify API token grants full access to your instance. If it's compromised:

Immediately revoke the token in Coolify
Remove the connection in EnvManager
Create a new token and reconnect

Secret visibility: Remember that anyone with access to your Coolify dashboard can view all environment variables, including those synced from EnvManager. EnvManager's access controls apply only within EnvManager itself.

Self-Hosted SSL

If you're using self-signed certificates:

Keep your CA certificate backed up securely
Update the CA certificate in EnvManager if it changes
Consider using Let's Encrypt for production to avoid SSL complexity

Troubleshooting

Connection Validation Fails

Problem: "Connection failed" or "Unable to connect to Coolify instance"

Solutions:

Verify your Coolify instance URL is correct and accessible from the internet
Check that your instance is running and responding
Ensure any firewalls or security groups allow incoming connections
Verify your API token hasn't been revoked

SSL Certificate Errors

Problem: "SSL certificate verification failed" or "Unable to verify the first certificate"

Solutions:

Enable "Allow self-signed certificate" in the connection settings
Provide your CA certificate in PEM format
Ensure the certificate includes the complete chain
Check that your Coolify instance's SSL certificate is valid and not expired

Resources Not Loading

Problem: No applications or services appear in the dropdown

Solutions:

Verify you have applications or services created in Coolify (databases are not sync targets, so they are not listed)
Check that your API token has permission to list resources
Read the message shown in the dialog - it names the reason, and says which resource types could not be loaded if only some failed
Try disconnecting and reconnecting the integration

Sync Fails

Problem: "Sync failed" error when trying to push variables

Solutions:

Verify your Coolify connection is still valid
Check that the target resource still exists in Coolify
Ensure your API token hasn't expired or been revoked
Review sync history for specific error messages

Saved Target No Longer Exists

Problem: Opening the configuration shows "The saved application no longer exists in Coolify", or a sync fails with "no longer exists. Reconfigure the integration"

This happens when the Coolify resource was deleted or recreated - recreating gives it a new UUID, so the one EnvManager stored no longer matches anything.

Solutions:

Open Configure and select the resource again for each affected environment
Save the configuration; syncing is blocked until every environment points at a resource that exists
If the whole list fails to load, the error message shown in the dialog explains why (unreachable instance, expired token, SSL problem) - fix that first, EnvManager will not mistake an unreachable instance for a deleted resource

Variables Not Applying

Problem: Variables synced successfully but application doesn't see them

Solutions:

Restart or redeploy the resource - Coolify only applies environment variables at container start. Enable Restart after sync to have EnvManager do it automatically
Check variable names match exactly what your application expects (including any prefix you configured)
Verify build variables are enabled if needed for build-time configuration
Review Coolify's application logs for environment variable issues

Deleted Variables Still in Coolify

Problem: A variable was deleted in EnvManager but is still set in Coolify

Solutions:

Run a sync - removals are applied on the next sync, not at the moment you delete the variable
Check the sync history: a partial status lists the keys that could not be removed, and they are retried on the next sync
Variables created directly in Coolify are deliberately never removed by EnvManager - delete those in Coolify

Database Targets Are Not Supported

Problem: A sync fails with "Coolify's API does not support environment variable sync for databases", or the configuration dialog refuses to save a database target

Coolify's API exposes environment variable endpoints for applications and services only - there is no equivalent for database resources, so EnvManager cannot manage their variables at all. This is a Coolify API limitation, not a permissions or version problem.

Solutions:

Select an application or service as the sync target instead
Set database credentials directly in Coolify, or store them in EnvManager and sync them to the application that connects to the database

Service Sync Issues

Problem: Can't sync to a service

Solutions:

Ensure you're running a recent version of Coolify that supports service variables
Verify the service is fully deployed and accessible
Check that the resource type is correctly identified in Coolify

Coolify Integration

Get DevOps tips in your inbox