Skip to content

Update and consolidate Docker Compose variable documentation. #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 17, 2025
Merged

Update and consolidate Docker Compose variable documentation. #367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1b3c871
Consolidated variable usage within Docker Compose, also added an addi…
bozau Oct 1, 2025
41faa7b
Updated location of changes to the docker compose knowledge base, pla…
bozau Oct 3, 2025
1a4c691
Fixed example image and added additional text explaining the value be…
bozau Oct 3, 2025
dc93f58
Merge branch 'next' into bozau/v4.x
Cinzya Oct 17, 2025
dff667a
fix(docs): escape Vue template syntax in Docker Compose documentation
Cinzya Oct 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 4 additions & 135 deletions docs/builds/packs/docker-compose.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,142 +98,11 @@ Then you can connect from `backend` to `auth` by referring to it as `http://auth

For further details, please refer to the [Docker Networking in Compose](https://docs.docker.com/compose/how-tos/networking/) docs.


## Advanced Configuration

### Defining Environment Variables

Coolify automatically detects environment variables mentioned in your compose file and displays them in the UI. For example:

```yaml
services:
myservice:
environment:
- SOME_HARDCODED_VALUE=hello # Passed to the container, but not visible in Coolify's UI.
- SOME_VARIABLE=${SOME_VARIABLE_IN_COOLIFY_UI} # Creates an editable, uninitialized variable in the UI.
- SOME_DEFAULT_VARIABLE=${OTHER_NAME_IN_COOLIFY:-hello} # Sets a default value "hello" that can be edited.
```

<ZoomableImage src="/docs/images/builds/packs/compose/6.webp" alt="Coolify dashboard screenshot" />

### Required Environment Variables

You can mark environment variables as required using the `:?` syntax. Required variables must be set before deployment and will be highlighted in Coolify's UI with a red border if empty.

```yaml
services:
myapp:
environment:
# Required variables - deployment will fail if not set
- DATABASE_URL=${DATABASE_URL:?}
- API_KEY=${API_KEY:?}

# Required variables with default values - prefilled in UI but can be changed
- PORT=${PORT:?3000}
- LOG_LEVEL=${LOG_LEVEL:?info}

# Optional variables - standard behavior
- DEBUG=${DEBUG:-false}
- CACHE_TTL=${CACHE_TTL:-3600}
```

**Key behaviors:**

- **Required variables** (`${VAR:?}`) appear first in the environment variables list and show a red border when empty
- **Required with defaults** (`${VAR:?default}`) are prefilled with the default value but remain editable
- **Optional variables** (`${VAR:-default}`) use standard Docker Compose behavior

If a required variable is not set during deployment:

- Coolify will highlight the missing variable in the UI
- The deployment will be prevented until all required variables are provided
- Clear error messages guide users to fix the configuration
### Using Environment and Shared Variables

This validation happens before container creation, preventing partial deployments and runtime failures.

### Coolify's Magic Environment Variables

Coolify can generate dynamic environment variables for you using the following syntax: `SERVICE_<TYPE>_<IDENTIFIER>`.

::: warning HEADS UP!
Support for Magic Environment Variables in Compose files based on Git sources has been added in Coolify v4.0.0-beta.411
:::

The types include:

| **Variables** | **Generated Value Type** |
| -------------------------------------- | -------------------------------------------------- |
| **PASSWORD** | Random Password (No Symbols) |
| **PASSWORD\_64** | Random Password (No Symbols, 64 characters) |
| **PASSWORDWITHSYMBOLS** | Random Password (With Symbols) |
| **PASSWORDWITHSYMBOLS\_64** | Random Password (With Symbols, 64 characters) |
| **BASE64\_64** | Random String (Not Base64-encoded, 64 characters) |
| **BASE64\_128** | Random String (Not Base64-encoded, 128 characters) |
| **BASE64** or **BASE64\_32** | Random String (Not Base64-encoded, 32 characters) |
| **REALBASE64\_64** | Random String (Base64-encoded, 64 characters) |
| **REALBASE64\_128** | Random String (Base64-encoded, 128 characters) |
| **REALBASE64** or **REALBASE64\_32** | Random String (Base64-encoded, 32 characters) |
| **HEX\_32** | Random String (Hexadecimal, 32 characters) |
| **HEX\_64** | Random String (Hexadecimal, 64 characters) |
| **HEX\_128** | Random String (Hexadecimal, 128 characters) |
| **USER** | Random String (16 characters) |
| **FQDN** | Fully Qualified Domain Name (FQDN) |
| **URL** | URL based on the defined FQDN |

Example:
```yaml
services:
appwrite:
environment:
- $SERVICE_PASSWORD: sjdkfhsd43f
- $SERVICE_PASSWORD_64: kdlfghsdiof43r3rweos93fofi39fjeowfkdj84fh3dksfjsw43r5
- $SERVICE_PASSWORDWITHSYMBOLS: sjdk@fhsd!43#f
- $SERVICE_PASSWORDWITHSYMBOLS_64: kdlfghsdiof43!@#r3rweos93fofi39fjeowfkdj84fh3dksfjsw43r5!
- $SERVICE_PASSWORD_BASE64_64: jkhf4r5g4dh7sd85sd85fh7sgd5fhdfgsd9g7sd
- $SERVICE_PASSWORD_BASE64_128: sd98fhsd7g8d98sd7f9sdg7fd87sd98f7sdg78f7d98g7d89
- $SERVICE_PASSWORD_BASE64: sd98fh3g2k3h2gs78d93dgh
- $SERVICE_PASSWORD_BASE64_32: sd98fh3g2k3h2gs78d93dgh
- $SERVICE_PASSWORD_REALBASE64_64: c2Q5OGZoc2Q3Z2g4Yzg1M2c5ZGM3MG5k8as==
- $SERVICE_PASSWORD_REALBASE64_128: c2Q5OGZoc2Q3Z2g4Yzg1M2c5ZGM3MG5k8aY9sdg==
- $SERVICE_PASSWORD_REALBASE64: c2Q5OGZoc2Q3Z2g4Yzg1M2c5ZGM3MG5k8a==
- $SERVICE_PASSWORD_REALBASE64_32: c2Q5OGZoc2Q3Z2g4Yzg1M2c5ZGM3MG5k8a==
- $SERVICE_PASSWORD_HEX_32: a6b9f34e43c112d79f9a3d5c7983344f
- $SERVICE_PASSWORD_HEX_64: db8c8a1a3b9df5a9fb8fd3f87df62f4b6a34cf4310f5cdb8c098b4f0e9af3b2
- $SERVICE_PASSWORD_HEX_128: 7f8c98a98db56b0c6c8768b1db6d24f5f39493433d8d8f1846598c9830202089
- $SERVICE_USER: jsd98fhg2j3skl8j
- $SERVICE_FQDN: api.example.com
- $SERVICE_URL: https://api.example.com
```

Every generated variable is consistent across all services in your stack and appears in Coolify's UI (except FQDN and URL, which are fixed).

For example, if your application UUID is `vgsco4o` and you deploy Appwrite on the wildcard domain `http://example.com`, you might include:

```yaml
services:
appwrite:
environment:
# Generates FQDN: http://appwrite-vgsco4o.example.com/v1/realtime
- SERVICE_FQDN_APPWRITE=/v1/realtime

# Uses the FQDN for _APP_URL.
- _APP_URL=$SERVICE_FQDN_APPWRITE

# Proxies to port 3000.
- SERVICE_FQDN_APPWRITE_3000

# Proxies API requests to port 2000.
- SERVICE_FQDN_API_2000=/api

# Generates and injects a password.
- SERVICE_SPECIFIC_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
not-appwrite:
environment:
# Reuses the password from the Appwrite service.
- APPWRITE_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
# Generates a new FQDN for this service.
- SERVICE_FQDN_API=/api
```
Within Coolify you can configure these easily following the details found in the [Knowledge Base for Docker Compose](/knowledge-base/compose#defining-environment-and-shared-variables).

### Storage

Expand Down Expand Up @@ -293,15 +162,15 @@ By default, each compose stack is deployed to a separate network named after you

If you want to connect services across different stacks (for example, linking an application to a separate database), enable the **Connect to Predefined Network** option on your Service Stack page.

<ZoomableImage src="/docs/images/builds/packs/compose/7.webp" alt="Coolify dashboard screenshot" />
<ZoomableImage src="/docs/images/builds/packs/compose/6.webp" />

Note that you must use the full name (like `postgres-<uuid>`) when referencing a service in another stack.

### Raw Docker Compose Deployment

For advanced users, Coolify offers a "Raw Compose Deployment" mode. This option lets you deploy your Docker Compose file directly without many of Coolify's additional configurations.

<ZoomableImage src="/docs/images/builds/packs/compose/8.webp" alt="Coolify dashboard screenshot" />
<ZoomableImage src="/docs/images/builds/packs/compose/7.webp" />

::: danger CAUTION
This mode is intended for advanced users familiar with Docker Compose.
Expand Down
94 changes: 66 additions & 28 deletions docs/knowledge-base/docker/compose.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,9 @@ Then you can connect from `backend` to `auth` by referring to it as `http://auth

For further details, please refer to the [Docker Networking in Compose](https://docs.docker.com/compose/how-tos/networking/) docs.

## Defining environment variables
## Defining Environment Variables

Coolify will notice the environment variables you mention in your compose file and will display it in its UI.
Coolify automatically detects environment variables mentioned in your compose file and displays them in the UI. For example:

```yaml
services:
Expand All @@ -72,28 +72,28 @@ services:
- SOME_DEFAULT_VARIABLE=${OTHER_NAME_IN_COOLIFY:-hello} # Creates an environment variable of value "hello" editable in Coolify's UI
```

<ZoomableImage src="/docs/images/screenshots/Docker-compose-environment-variables-UI.webp" alt="Docker Compose Environment Variables Ui configuration" />
<ZoomableImage src="/docs/images/knowledge-base/compose/1.webp" />

## Required environment variables
### Required Environment Variables

Coolify supports marking environment variables as required using Docker Compose's built-in syntax. This feature improves the deployment experience by validating critical configuration before starting services.

### Syntax

Use the `:?` syntax to mark variables as required:
You can mark environment variables as required using the `:?` syntax. Required variables must be set before deployment and will be highlighted in Coolify's UI with a red border if empty.

```yaml
services:
webapp:
myapp:
environment:
# Required variable - must be set, no default
# Required variables - deployment will fail if not set
- DATABASE_URL=${DATABASE_URL:?}
- API_KEY=${API_KEY:?}

# Required variable with default value - prefilled but editable
# Required variables with default values - prefilled in UI but can be changed
- PORT=${PORT:?3000}
- LOG_LEVEL=${LOG_LEVEL:?info}

# Optional variable with default - standard Docker Compose behavior
# Optional variables - standard behavior
- DEBUG=${DEBUG:-false}
- CACHE_TTL=${CACHE_TTL:-3600}
```

**Key behaviors:**
Copy link
Member

@Cinzya Cinzya Oct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't this + the magic environment section be moved as well then? They work the same across both as well.

Copy link
Contributor Author

@bozau bozau Oct 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll check it out, I haven't personally used any of the magic variables in my docker compose, but I suspect you'll be correct.
From what I understand, the magic variables are across all of Coolify, and not docker compose specific right? If so, they probably should sit in the Environment Variables page, yeah?

Copy link
Member

@Cinzya Cinzya Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are actually Docker Compose specific, so I would say we add them in the Environment Variables page under Docker Compose.
Appreciate the work btw! 😊

Expand All @@ -110,35 +110,71 @@ If a required variable is not set during deployment:

This validation happens before container creation, preventing partial deployments and runtime failures.

## Coolify's magic environment variables
### Shared Environment Variables

Coolify doesn't directly detect **shared** environment variables in the compose file, but are able to be referenced using with an additional step.

1. Create your shared variable following the [shared variables documentation](/knowledge-base/environment-variables#shared-variables).

2. Define your variables in your Docker Compose file, for example;

```yaml
services:
myservice:
environment:
- HARD_CODED=dev # Passed to the container, but not visible in Coolify's UI.
- SOME_OPTIONAL_VARIABLE=${SOME_VARIABLE_IN_COOLIFY_UI} # Creates an editable, uninitialized variable in the UI.
volumes:
- data-persist:/var/data
volumes:
data-persist:
device: /mnt/serverstorage/${SOME_VARIABLE_IN_COOLIFY_UI} # Re-uses the variable
```

3. Define the variable explicitly in the applications Environment Variables referencing your shared variable created in step 1;

::: v-pre

If in developer view, you can enter it like so;

```
SOME_VARIABLE_IN_COOLIFY_UI={{environment.SOME_SHARED_VARIABLE}}
```

Or in the normal view, the Name is what's referenced in the Docker Compose file `SOME_VARIABLE_IN_COOLIFY_UI` with the Value being the referenced environment variable `{{environment.SOME_SHARED_VARIABLE}}` as seen below. Once saved if correct, you'll see there's a third text box, if you reveal this, you should be able to see the true value, in this case `SOME_VALUE`.

:::

<ZoomableImage src="/docs/images/knowledge-base/compose/2.webp" />

Additionally, Coolify can generate some dynamic environment variables for you.
The syntax is `SERVICE_<TYPE>_<IDENTIFIER>`.
Type may be one of:
### Coolify's Magic Environment Variables

- **FQDN**: This will [generate](/knowledge-base/server/introduction#wildcard-domain) an FQDN for the service. The example below shows how you can add paths and ports.
- **URL**: Generates an URL based on the FQDN you have defined. Prefer this to generate URL for your services
Coolify can generate dynamic environment variables for you using the following syntax: `SERVICE_<TYPE>_<IDENTIFIER>`. The type may be one of:

- **URL**: This will [generate](/knowledge-base/server/introduction#wildcard-domain) an URL for the service. The example below shows how you can add paths and ports.
- **FQDN**: Generates FQDN for the service based on the URL you have defined. The example below shows how you can add paths and ports.
- **USER**: Generates a random string using `Str::random(16)`. You might want to use it as a username in your service.
- **PASSWORD**: Generates a password using `Str::password(symbols: false)`. Use `PASSWORD_64` to generate a 64 bit long password with `Str::password(length: 64, symbols: false)`.
- **BASE64**: Generates a random string using `Str::random(32)`. For longer strings, use `BASE64_64` or `BASE64_128`.
- **REALBASE64**: Encodes a randomly generated string using `base64_encode(Str::random(32))`. For longer strings, use `REALBASE64_64` or `REALBASE64_128`.

Every generated variable can be reused and will always have the same value for every service.
All generated variables are displayed in Coolify's UI for environment variables and can be edited there (except FQDN and URl).

::: info Naming
Names with underscores (`_`) cannot use ports in environment variables. Use hyphens (`-`) instead to avoid this limitation.
::: info Identifier Naming
Identifier with underscores (`_`) cannot use ports in environment variables. Use hyphens (`-`) instead to avoid this limitation.

```
SERVICE_URL_APPWRITE_SERVICE_3000 ❌
SERVICE_URL_APPWRITE-SERVICE_3000 ✅
```

:::

Every generated variable can be reused and will always have the same value for every service.
All generated variables are displayed in Coolify's UI for environment variables and can be edited there (except FQDN and URl).

As an example, imagine an application with UUID `vgsco4o` (generated by Coolify on creation).
It uses a compose file deploying Appwrite on the [wildcard](/knowledge-base/server/introduction#wildcard-domain) domain `http://example.com` .

This will do the following:
This will do the following:

- `SERVICE_URL_APPWRITE`: 'http://appwrite-vgsco4o.example.com'
- `SERVICE_FQDN_APPWRITE`: appwrite-vgsco4o.example.com

Expand All @@ -160,15 +196,17 @@ services:
- SERVICE_SPECIFIC_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
not-appwrite:
environment:
# Same value as in Appwrite service
# Reuses the password from the Appwrite service.
- APPWRITE_PASSWORD=${SERVICE_PASSWORD_APPWRITE}
# As SERVICE_URL_API is not the same as SERVICE_URL_APPWRITE
# Coolify will generate a new URL
# http://not-appwrite-vgsco4o.example.com/api
- SERVICE_URL_API=/api
```

---
:::Warning
Support for Magic Environment Variables in Compose files based on Git sources requires Coolify v4.0.0-beta.411 and above.
:::

## Storage

Expand All @@ -195,7 +233,7 @@ Here you can see how to add a file with content and a dynamic value that is comi
```yaml
services:
filebrowser:
image: filebrowser/filebrowser:latest
image: filebrowser/firebrowser:latest
environment:
- POSTGRES_PASSWORD=password
volumes:
Expand Down
15 changes: 2 additions & 13 deletions docs/knowledge-base/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,20 +37,9 @@ You can set them on the `Projects` page, under the gear icon and use it with <co

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

#### Using Shared Variables in Compose File
### Using Environment and Shared Variables in Docker Compose

If you want to use the environment variables in your compose file, you can do so by using the following syntax:

```bash
environment:
- NODE_ENV=${NODE_ENV}
```

And then in the UI set `NODE_ENV` to your desired shared variable. For example if you want to use a team based variable (make sure you have the `NODE_ENV` variable set in the Team Variables):

```bash
NODE_ENV={{team.NODE_ENV}}
```
Within Coolify you can configure these easily following the details found in the [Knowledge Base for Docker Compose](/knowledge-base/compose#defining-environment-and-shared-variables).

## Predefined Variables

Expand Down
Binary file modified docs/public/images/builds/packs/compose/6.webp
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/public/images/builds/packs/compose/7.webp
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/public/images/builds/packs/compose/8.webp
View file
Open in desktop
Binary file not shown.
Binary file added docs/public/images/knowledge-base/compose/1.webp
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/public/images/knowledge-base/compose/2.webp
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.