Docs Build and deploy

Variables and references

Variables are the environment variables a service runs with. Each environment has its own set, so production and staging can use different values. Values are encrypted at rest.

Service variables

Open a service and go to the Variables tab. Click New variable to add one, click a value to edit it, and click Save changes. Raw editor switches to a .env view with one KEY=value per line; saving it replaces all the service’s variables except sealed ones. You can also paste several KEY=value lines into a new variable’s name field.

Names may contain letters, digits, _, . and -, and must not start with a digit. One service or environment can hold 256 KB of variables, and a workspace 2 MB on Trial, 32 MB on Hobby and 128 MB on Pro. Keep large files in a volume.

From the CLI:

dawn vars set NODE_ENV=production LOG_LEVEL=info
dawn vars set < .env
dawn vars unset LOG_LEVEL

Shared variables

Shared variables belong to an environment rather than a service. Edit them in the project’s Settings, under Shared variables, or with dawn vars set --shared KEY=VALUE.

A shared variable reaches a service only through a reference. To give a service the value, add a variable to it such as:

SENTRY_DSN=${{ shared.SENTRY_DSN }}

References

A value can contain references in ${{ … }}. Dawnrose resolves them when it deploys the service.

Reference	Resolves to
`${{ Postgres.DATABASE_URL }}`	The variable `DATABASE_URL` of the service named Postgres in the same environment.
`${{ shared.KEY }}`	The shared variable `KEY` of the environment. `project.KEY` and `environment.KEY` work the same way.
`${{ KEY }}`	Another variable of the same service.

Service names match without regard to case, and a service’s slug works too. A reference can point at a variable Dawnrose provides, for example ${{ api.DAWNROSE_PRIVATE_DOMAIN }}. Values can mix text and references:

API_URL=http://${{ api.DAWNROSE_PRIVATE_DOMAIN }}:8080/v1

In the editor, type ${{ in a value to get suggestions. The Resolved button shows each value with its references filled in, and errors such as an unknown service or key are listed above the variables. The project canvas draws a line for each reference between services.

A deployment fails if a reference cannot be resolved; the deploy log lists each one along with the services or keys that do exist. A variable that references itself, directly or through others, is refused when you save it.

Generated values

These functions are replaced with a random value once, when you save the variable. The stored value does not change after that.

Function	Produces
`${{ secret() }}`	32 random letters and digits.
`${{ secret(48) }}`	The given number of letters and digits, up to 256.
`${{ secret(32, "abcdef0123456789") }}`	The given number of characters drawn from the given alphabet.
`${{ password() }}`	A 20-character password of letters and digits with at least one uppercase letter, one lowercase letter and one digit. Characters that are easy to confuse are left out.
`${{ password(32) }}`	The same with the given length, from 12 to 64.
`${{ randomInt() }}`	A whole number from 0 to 1,000,000.
`${{ randomInt(1, 100) }}`	A whole number in the given range, inclusive.

Generated values can be part of a longer value, as in sk-${{ secret(40) }}.

Sealed variables

A sealed variable can be written but never read back. Its value is still given to the service at runtime, but the dashboard, the API, the CLI and agents only see that it exists. A variable whose value references a sealed one is hidden in the resolved view as well.

In the dashboard, open the variable’s menu and choose Seal value.
From the CLI, add --sealed: dawn vars set API_KEY=… --sealed.
Agents pass the key in the sealed list of set_variables.

Sealing cannot be undone, but you can replace the value: click the sealed value and enter a new one. Sealed variables are not copied when you duplicate an environment, and dawn vars pull, dawn run and dawn shell leave them out.

Workspace viewers can read the variables of the projects they can open. Seal anything they should not see.

Variables Dawnrose provides

Every service gets these variables. The Provided by Dawnrose section at the bottom of the Variables tab lists their current values. A variable you set with the same name replaces the provided one.

Variable	Value
`PORT`	The port Dawnrose routes traffic to, unless you set `PORT`. See Ports.
`DAWNROSE_PROJECT_ID`, `DAWNROSE_PROJECT_NAME`	The project.
`DAWNROSE_ENVIRONMENT_ID`, `DAWNROSE_ENVIRONMENT_NAME`	The environment.
`DAWNROSE_SERVICE_ID`, `DAWNROSE_SERVICE_NAME`	The service.
`DAWNROSE_PRIVATE_DOMAIN`	The private hostname, `<service>.dawnrose.internal`.
`DAWNROSE_PUBLIC_DOMAIN`	The hostname of the service’s first domain, or empty.
`DAWNROSE_TCP_PROXY_DOMAIN`, `DAWNROSE_TCP_PROXY_PORT`, `DAWNROSE_TCP_APPLICATION_PORT`	The public host and port of the TCP proxy and the port it forwards to. Only with a TCP proxy.
`DAWNROSE_VOLUME_NAME`, `DAWNROSE_VOLUME_MOUNT_PATH`	The volume. Only with a volume.
`DAWNROSE_DEPLOYMENT_ID`	The deployment.
`DAWNROSE_REPLICA_ID`	The replica, unique per replica of a deployment.
`DAWNROSE_GIT_REPO`	The repository, for services that deploy one.
`DAWNROSE_GIT_BRANCH`, `DAWNROSE_GIT_COMMIT_SHA`, `DAWNROSE_GIT_COMMIT_MESSAGE`	The deployed branch, commit and the first line of its message, when known.

When changes take effect

Saving variables does not touch the running deployment. The change is staged: the canvas shows a banner listing the services with changes, and the next deployment of a service uses its new variables. Click Deploy in the banner to deploy every changed service, or see Deploying pending changes.

dawn vars set and dawn vars unset redeploy for you unless you pass --skip-deploy. Agents can pass deploy: true to set_variables to deploy the service right after changing its variables.

Variables are also available during the build: Dawnrose passes the resolved values to Docker builds as build arguments, which a Dockerfile reads with ARG.