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, databases, 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)
Database - A managed database instance
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.

Choose Your Target Resource

From the dropdown menu, select the specific application, database, 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)
Databases show their type (PostgreSQL, MySQL, etc.)
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
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.

Deployment Required: After syncing variables, you'll need to redeploy your Coolify application for the changes to take effect. Coolify doesn't automatically restart containers when environment variables change.

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. You'll see a success message when complete.

Redeploy in Coolify

Go to your Coolify dashboard and redeploy the application to apply the new environment variables.

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

You'll still need to manually redeploy your Coolify application after auto-sync completes.

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 or failed
Variables synced - Number of variables pushed to Coolify
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, databases, or services appear in the dropdown

Solutions:

Verify you have resources created in Coolify
Check that your API token has permission to list resources
Try disconnecting and reconnecting the integration
Check the browser console for specific error messages

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

Variables Not Applying

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

Solutions:

Redeploy your Coolify application (required for changes to take effect)
Check variable names match exactly what your application expects
Verify build variables are enabled if needed for build-time configuration
Review Coolify's application logs for environment variable issues

Database or Service Sync Issues

Problem: Can't sync to databases or services, only applications

Solutions:

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

Coolify Integration

Get DevOps tips in your inbox