Environment Variables

Environment variables (opens in a new tab) are a common method of passing configuration data to applications at runtime. You can define environment variables on Koyeb to pass important information to your Services. These variables are exposed during the build process and at runtime.

Each environment variable has the following components:

Name: The name of the environment variable.
Value: The value that will be given when the variable is accessed. The value can be a plaintext value, or leverage interpolation to reference Secrets, a Koyeb-provided variables, or other environment variables.

Koyeb Web Services always have a PORT variable defined. If the PORT environment variable is not set explicitly, it will be automatically set to the lowest exposed port number. You can set the PORT variable manually in the environment variable configuration if you wish to point it to a different port.

Managing environment variables

You can define and modify environment variables using either the Koyeb control panel (opens in a new tab) or the Koyeb CLI.

When using the Koyeb control panel, you can manage environment variables for your Service on the Service configuration screen. This screen is accessible both during your initial Service configuration and later in your Service's Settings tab.

From the Settings tab, expand the Environment variables and files section. From here, you can manage variables in two ways:

Manage individual variables

You can manage individual variables with the provided buttons.

To add a new variable, click Add Variable. Choose a name for the variable and then set the value.

To modify an existing variable, edit the variable's name, or value.

To delete a variable, click the trash icon associated with the environment variable line.

Perform bulk editing

To edit environment variables in bulk, click Bulk Edit.

This will open up a free-form text box pre-populated with the form's current environment variable configuration. Each variable is defined on its own line using the following format:

<ENV_NAME>=<ENV_VALUE>

To set a value that spans multiple lines, wrap the value in single quotes, double quotes, or backticks:

PUBLIC_KEY="-----BEGIN PGP PUBLIC KEY BLOCK-----
Comment: ABAF 11C6 5A29 70B1 30AB  E3C4 79BE 3E43 0041 1886

xsBNBE55CJIBCACkn+aOLmsaq1ejUcXCAOXkO3w7eiLqjR/ziTL2KZ30p7bxP8cT
UXvfM7fwE7EnqCCkji25x2xsoKXB8AlUswIEYUFCOupj2BOsVmJ/rKZW7fCvKTOK
+BguKjebDxNbgmif39bfSnHDWrW832f5HrYmZn7a/VySDQFdul8Gl/R6gs6PHJbg
jjt+K7Px6cQVMVNvY/VBWdvA1zckO/4h6gf3kWWZN+Wlq8wv/pxft8QzNFgweH9o
5bj4tnQ+wMCLCLiDsgEuVawoOAkg3dRMugIUoiKoBKw7b21q9Vjp4jezRvciC6Ys
4kGUSFG1ZjIn3MpY3f3xZ3yuYwrxQ8JcA7KTABEBAAHOwE0ETnkIkgEIAN+ybgD0
IlgKRPJ3eksafd+KORseBWwxUy3GH0yAg/4jZCsfHZ7jpbRKzxNTKW1kE6ClSqeh
UsuXT5Vc1eh6079erN3y+JNxl6zZPC9v+5GNyc28qSfNejt4wmwa/y86T7oQfgo7
7o8Gu/aO/xzOjw7jSDDR3u9p/hFVtsqzptxZzvs3hVaiLS+0mar9qYZheaCUqOXO
KVo38Vg5gkOhMEwKvZs9x3fINU/t8ckxOHq6KiLap5Bq87XP0ZJsCaMBwdLYhOFx
AiEVtlzwyo3DvMplIahqqNELb71YDhpMq/Hu+42oR3pqASCPLfO/0GUSdAGXJVhv
7L7ng02ETSBmVOUAEQEAAcLAdgQYAQIACQUCTnkIkgIbDAAhCRB5vj5DAEEYhhYh
BKuvEcZaKXCxMKvjxHm+PkMAQRiG6hsH/0WLUZUbmqc+rXhLRYpgRbc3z3Uvfstp
eYOH3vuv+PZ3Jk6hgiJXivHprq6uGr1RtyA3D+R7TVM0zjLsSFb+UWfElBdIyN2x
cZxv0fBR68OTYUxXWH2CQcuWpFSVOmNV1DBMH3Ax3htaFmzHJtOcaHqjx0LAERoY
2wexIFg7zU5etMT99xkSAoJ4pbbF0pGJrO7oy7lYtTqAHLac5zqgvbMolmMAJ+WV
DMHHn7rPY3hKPQkE6hvPhFHYksSUwRyQxt2pshL5z6fTYi0yYI5GBqR/viT5MRtp
nHdlNUeeG+pCpqdnPWLgjkjAcnGRSxgt12BivKVkf4zA0OUHm7cjXfw=
=HpqG
-----END PGP PUBLIC KEY BLOCK-----"

Click the Save button when you are finished with the bulk edit operation. The environment variable fields on the configuration page will immediately update to reflect the new variable definitions. After completing your changes, click the Deploy button to create a new Deployment with the provided environment variables.

Environment variable and Secret interpolation

Variable interpolation, also known as variable substitution or expansion, is the process of replacing a reference to a variable with its defined value. Koyeb supports environment variable interpolation, meaning that you can refer to other environment variables when defining a variable value. Koyeb will replace all environment variable references with their respective values during processing.

To reference the value of an environment variable, use the following syntax:

{{ <ENV_NAME> }}

For example, the following definition defines two variables. The second variable refers to the value of the first:

STORAGE_REGION=eu-central-003
STORAGE_ENDPOINT=https://storage.{{ STORAGE_REGION }}.provider.com

This definition will result in the following variable values:

STORAGE_REGION=eu-central-003
STORAGE_ENDPOINT=https://storage.eu-central-003.provider.com

To set an environment variable's value to the content of a Koyeb Secret, use the following syntax:

{{ secret.<SECRET_NAME> }}

For example, to set a variable called DB_PASSWORD to a Secret called POSTGRESQL_PASS, name your your environment variable DB_PASSWORD and add the following value:

{{ secret.POSTGRESQL_PASS }}

When performing bulk edit, add the following line:

DB_PASSWORD={{ secret.POSTGRESQL_PASS }}

💡

Note: References to undefined variables will be replaced by a blank string during processing.

In the example below, the STORAGE_ENDPOINT definition accidentally refers to the STORAGEREGION variable (which does not exist) instead of the STORAGE_REGION variable:

STORAGE_REGION=eu-central-003
# The definition below does not reference the correct variable name
STORAGE_ENDPOINT=https://storage.{{ STORAGEREGION }}.provider.com

This will result in the following, unintended, variable values:

STORAGE_REGION=eu-central-003
STORAGE_ENDPOINT=https://storage..provider.com

Updating an environment variable at runtime will not change the values of variables that reference it. Koyeb only processes environment variables for interpolation during the actual deployment and will not re-evaluate variables based on later changes.

You can also refer to Koyeb-provided variables, such as KOYEB_PUBLIC_DOMAIN, when defining a variable value. This strategy allows you to refer to values (like the App's public domain) that are only known at runtime.

For example, our Django deployment guide uses the DJANGO_ALLOWED_HOSTS environment variable to pass in the domain name where the application is hosted. You can automatically populate the correct value by defining it in terms of the KOYEB_PUBLIC_DOMAIN variable:

DJANGO_ALLOWED_HOSTS={{ KOYEB_PUBLIC_DOMAIN }}

With this, the DJANGO_ALLOWED_HOSTS variable will automatically be set to the public domain of your App.

Koyeb-provided variables

Koyeb automatically exposes information about your Service's deployment environment and configuration as environment variables.

The following Koyeb environment variables are exposed to your Services automatically both during the build and at runtime:

Variable	Details
`KOYEB_APP_NAME`	Description: Koyeb Application name. Example: `app`
`KOYEB_APP_ID`	Description: Koyeb Application ID. Example: `647813c7-09b8-44ce-a02a-0cc70092bf4c`
`KOYEB_ORGANIZATION_NAME`	Description: Koyeb Organization name. Example: `my-organization`
`KOYEB_ORGANIZATION_ID`	Description: Koyeb Organization ID. Example: `6704aff2-36ec-4e13-ba1e-0438eaf7a65e`
`KOYEB_SERVICE_NAME`	Description: Koyeb Service name. Example: `my-service`
`KOYEB_SERVICE_ID`	Description: Koyeb Service ID. Example: `41dcf9cb-53a4-4b02-960c-f421254a1678`
`KOYEB_SERVICE_PRIVATE_DOMAIN`	Description: Default Service URL for service discovery. Example: `<SERVICE_NAME>.<APP_NAME>.internal`
`KOYEB_PUBLIC_DOMAIN`	Description: Default public Service URL. Only routable for `web` Services. Example: `<APP_NAME>-<ORGANIZATION>-<HASH>.koyeb.app`
`KOYEB_PORT_<PORT>_PROTOCOL`	Description: The protocol of the exposed port `<PORT>`. Can be `tcp`, `http`, or `http2`. Example: `http`
`KOYEB_PRIVILEGED`	Description: Whether the container is running in privileged mode (opens in a new tab). Can be `true` or `false`. Example: `true`
`KOYEB_DOCKER_REF`	Description: The Docker container's image reference (opens in a new tab) as specified by the user in the CLI or the control panel. Example: `koyeb/demo:latest` Availability: Only for Docker deployments
`KOYEB_GIT_SHA`	Description: The SHA (opens in a new tab) of deployed Git commit. Example: `ac18568cd565650e96216c8d092a6c60f9ed09b` Availability: Only for GitHub deployments
`KOYEB_GIT_BRANCH`	Description: Git branch name of the currently deployed Service. Example: `main` Availability: Only for GitHub deployments
`KOYEB_GIT_REPOSITORY`	Description: Git repository URL of the deployed Service. Example: `github.com/koyeb/example-qwik` Availability: Only for GitHub deployments
`KOYEB_GIT_COMMIT_MESSAGE`	Description: Commit message of the deployed Git commit. Example: `Fix README heading` Availability: Only for GitHub deployments
`KOYEB_GIT_COMMIT_AUTHOR`	Description: Commit author of the deployed Git commit. Example: `Cindy Davis` Availability: Only for GitHub deployments

The following environment variables are exposed to your Service at runtime only (after the build):

Variable	Details
`KOYEB_REGION`	Description: Region where the service is deployed. Example: `fra`
`KOYEB_REGIONAL_DEPLOYMENT_ID`	Description: Regional Deployment ID of the Service, which may be helpful for support. Example: `3a1bb3d0-7502-40a5-ae12-7e28f807531b`
`KOYEB_INSTANCE_ID`	Description: Koyeb Instance ID. Example: `e5f296b6-a911-8637-234e-f929e8bd5d87`
`KOYEB_INSTANCE_TYPE`	Description: Type of Instance running the Service. Example: `nano`
`KOYEB_INSTANCE_MEMORY_MB`	Description: The memory allocated to the Instance, in MB. Example: `256`
`KOYEB_REPLICA_INDEX`	Description: The 0-based index number of the replica. This may be useful, for example, for configuring leader elections. Example: `0`
`KOYEB_HYPERVISOR_ID`	Description: The ID of the hypervisor the Service is running on, which may be helpful for support. Example: `fra1-rn23u23`
`KOYEB_DC`	Description: The data center the Service is deployed to (within a region), which may be helpful for support. Example: `fra1`
`KOYEB_GPU_COUNT`	Description: The number of GPUs available on the Instance. Example: `2`

Your Services can read the values of these environment variables to get contextual information about their deployment and runtime environment.

Using environment variables in your applications

An environment variable's value can be accessed within your application using your language's environment variable functionality.

For example, if you set an environment variable called DATABASE_URL, you could access it like this:

process.env.DATABASE_URL

Accessing environment variables during Dockerfile builds

If you are using the Dockerfile build process and you wish to access environment variables during the build, you must have ARG instructions (opens in a new tab) in your Dockerfile defining the environment variables you wish to use.

For example, to access the Koyeb-provided KOYEB_PUBLIC_DOMAIN variable and a custom variable called APP_REDIS_URL during your Dockerfile build, add the following lines to your Dockerfile:

. . .
ARG KOYEB_PUBLIC_DOMAIN
ARG APP_REDIS_URL=localhost:6379

The second ARG instruction above includes a default value that will be used if you do not define the environment variable during the build process. The KOYEB_PUBLIC_DOMAIN does not include a default value, so that variable is required at build time. Fortunately, Koyeb will automatically set that variable for public web services.

Private Container Registry Secrets Config Files