Environment Variables

You can define environment variables for your resources, and they will be available in your application.

Preview Deployments could have different environment variables, so you can test your application as a staging environment for example.

Normal View vs Developer View

Coolify provides two ways to manage environment variables: Normal view and Developer view. You can switch between them using the button at the top of the environment variables section.

Normal View

The default view displays each environment variable as an individual form card. Each card includes editable key and value fields, along with checkboxes for options like Build Variable, Multiline, and Literal.

This view is best when you need to configure individual variables with specific options, or when working with multiline values and locked secrets.

Developer View

The Developer view provides a plain-text editor where all environment variables are displayed in .env file format (KEY=VALUE, one per line). This is useful for bulk editing or pasting variables from an existing .env file.

When saving, Coolify parses the text and creates, updates, or removes variables accordingly. The order of variables in the text editor is preserved.

Build Time vs Runtime Variables

Every environment variable has two independent flags that control when it is available: Build Variable and Runtime Variable. Both are enabled by default, so new variables are available in both phases unless you change this.

You can toggle these checkboxes independently in the Normal view.

Build Variables

Build variables are injected during the image build process. For Dockerfile deployments, they are added as ARG instructions. For Docker Compose and Nixpacks/Buildpack deployments, they are passed via --env-file.

Build-time variables are stored in a separate file (/artifacts/build-time.env) outside the Docker build context, so they are not included in the final image.

Runtime Variables

Runtime variables are available inside the running container. After the build completes, Coolify writes a .env file containing all runtime-enabled variables, which is loaded by Docker Compose via the env_file directive at container start.

Docker Build Secrets

By default, build variables are passed as --build-arg values. These values get recorded in the image metadata — anyone with access to the image can reveal them. For sensitive values like private registry tokens or API keys, you can enable Use Docker Build Secrets in your application's environment variable settings. This uses Docker BuildKit (requires Docker 18.09+) to temporarily mount secrets into build steps instead of embedding them in image layers, so they leave no trace in the final image.

When enabled, Coolify automatically rewrites your Dockerfile's RUN instructions to use --mount=type=secret — you do not need to modify your Dockerfile manually. For Docker Compose builds, Coolify adds a native secrets: section to the compose file instead.

When enabled, Coolify:

1. Passes build variables via --secret id=KEY,env=KEY instead of --build-arg.
2. Automatically adds a # syntax=docker/dockerfile:1 directive to your Dockerfile if missing.
3. Injects --mount=type=secret into every RUN instruction, making secrets available as environment variables during that step.
4. Secrets are never embedded in image layers and are not visible in docker history.

For Docker Compose builds, Coolify adds a native secrets: section to the compose file instead.

Multiline Variables

The Multiline checkbox in Normal view preserves line breaks and special characters in your variable's value. Enable this when your value spans multiple lines, such as:

• SSH private keys
• TLS/SSL certificates
• Multi-line configuration files or scripts

Multiline values are wrapped in single quotes during deployment, which prevents any shell interpretation. During Docker builds, multiline build variables are passed using ARG KEY without inline value assignment to avoid breaking Dockerfile syntax — the actual value is supplied separately via --build-arg.

Literal Variables

The Literal checkbox in Normal view prevents variable interpolation. By default, Coolify expands references like $OTHER_VAR inside your value. Enabling Literal treats the entire value as plain text — dollar signs and other shell-special characters are preserved as-is.

Use this when your value contains $ characters that should not be interpreted as variable references:

• Passwords containing $ (e.g., P@ss$word123)
• Regex patterns (e.g., ^user\d+$)
• Templating syntax or literal shell expressions

Shared Variables

You could have 3 types of shared variables:

1. Team Based
2. Project Based
3. Environment Based (production, staging, etc.)

You can set shared variables on their respective pages.

Then you can use these variables anywhere. For example: You defined NODE_ENV to production.

Team Based

You can set them on the Team page and use it with {{team.NODE_ENV}}. Do not replace "team" with your actual team name.

Project Based

You can set them on the Projects page, under the gear icon and use it with {{project.NODE_ENV}}. Do not replace "project" with your actual project name.

Environment Based

You can set them on the Environments page (select a Project), under the gear icon and use it with {{environment.NODE_ENV}} Do not replace "environment" with your actual environment name.

Using Environment and Shared Variables in Docker Compose

Within Coolify you can configure these easily following the details found in the Knowledge Base for Docker Compose.

Predefined Variables

Coolify predefines some variables for you, so you can use them in your application or service. All you need to do is to add an environment variable like this to your application or service.

# For example, you can use this variable in your application
MY_VARIABLE=$SOURCE_COMMIT
# You will have the commit hash of the source code in your application as an environment variable in MY_VARIABLE

Application Variables

COOLIFY_FQDN

Fully qualified domain name(s) of the application.

COOLIFY_URL

URL(s) of the application.

COOLIFY_BRANCH

Branch name of the source code.

COOLIFY_RESOURCE_UUID

Unique resource identifier generated by Coolify.

COOLIFY_CONTAINER_NAME

Name of the container generated by Coolify.

SOURCE_COMMIT

Commit hash of the source code.

PORT

If not set: it is set to the Port Exposes's first port.

HOST

If not set: it is set to 0.0.0.0

Service Stack Variables

SERVICE_NAME_<ID>

The service name of a given service in the stack. For example, if you have a service named web, you can access it with SERVICE_NAME_WEB. Useful for preview deployments where service names will vary.

Magic Environment Variables

For Docker Compose / Service Stack deployments, Coolify can auto-generate dynamic values using the SERVICE_<TYPE>_<IDENTIFIER> syntax. These let you generate URLs, FQDNs, passwords, and random strings that stay consistent across all services in a stack.

Generated values are reusable across services and persist between deployments. For full usage examples in a compose file, see Magic Environment Variables in Docker Compose.