Skip to content
NebulaCtrldocs
Guides

Run release commands and mount files

Run a command such as a database migration before each release starts, and mount a service's variables as read-only files.

A release command runs once per deployment, before any process of the new release starts. Files from variables mount some of a service's variables as read-only files, for apps that read a secret from a path such as /run/secrets/api-key.

Before you begin

  • You need the deployer role.
  • The service must not be a database service: its process is its template's own, so it takes neither setting.
  • Both settings belong to the service and save at once. A release freezes them when it is created, so they apply from the next deployment.

Set a release command

Select the service on the canvas, then the Settings tab.

Under Release command, enter the Command, for example bin/migrate --yes. Words split on spaces, and quotes keep a phrase together. Leave the field empty for none. The limit is 8 KiB in total.

Optionally set Timeout (seconds), from 1 to 3600. Empty means 300. The field is disabled while the command is empty.

Select Save release command. A toast reads "Release command saved. It runs before the next release starts."

What happens at a deploy

The deployment passes through a Release command stage between Admitted and Starting. The cluster's agent runs the command as a one-off job in the environment's namespace:

  • It uses the new release's image, its variables and its mounted files, and no volumes.
  • The command replaces the image's CMD and keeps its ENTRYPOINT.
  • It gets the resources of the service's first HTTP process, or 0.25 vCPU requested, 1 vCPU limit, 256 MiB requested and 512 MiB limit when the service has none.
  • It runs as the user of the service's first HTTP process or, with no HTTP process, of the first process by name that sets a Run as user. If the image runs as root or as a named user and that choice is unset, the deploy is refused with a message that starts runAsUser must be set for the release command. See Run a process as another user.
  • It runs once and is not retried.

If the command exits with status 0, the processes start. When a deployment has to stop the previous release first, as for a service with a volume, the command still runs before that.

If the command fails, the deployment fails with the release-command blocker and the previous release keeps serving. The message names the cause, then the last 20 log lines. Values of secret variables that are at least 6 characters long show as [redacted]:

release command exited 1
release command timed out after 10m0s

Fix the command or the data, then deploy again. A deploy that is refused with "this cluster's agent can't run release commands yet" needs an agent update; on an older cluster, re-apply the manifest.

Mount a variable as a file

Add the variable on the service's Variables tab, for example API_KEY. See Set variables and references.

On the Settings tab, under Files from variables, select Add file.

Enter the absolute Path, for example /run/secrets/api-key, and choose the variable from the list. Only the service's own variables are listed.

Select Save files. A toast reads "Files saved. The next release mounts them read-only; deploy to apply."

Then point the app at the path, for example with a variable API_KEY_FILE set to /run/secrets/api-key.

Every container of the release mounts each file read-only with mode 0444: every process and the release command. The file holds the variable's value at the time the release is created.

A file path is refused when it:

  • is not an absolute, clean path, or ends in /;
  • is under /proc, /sys or /dev;
  • sits directly in /, /etc, /usr, /bin, /sbin, /lib, /var or /tmp;
  • is at or inside a volume's mount path;
  • repeats another file's path.

A service holds at most 20 files. The key must match ^[A-Z_][A-Z0-9_]*$.

A file's whole directory is mounted read-only. Give files a directory of their own, such as /run/secrets/, because anything the image keeps in that directory is hidden.

If a deploy names a variable that the environment lacks, it is refused with "API_KEY is not set for this environment, so /run/secrets/api-key has nothing to hold; set API_KEY in the service's variables or remove the file". A cluster whose agent can't mount files refuses the deploy with "this cluster's agent can't mount files yet"; see Deployments troubleshooting. A nebula.toml has no key for files, because a secret's value must not come from Git.

Verify

Deploy the service. On the Deployments tab, the release shows Release command as a stage that completes, then Starting. To confirm a file is mounted, have the app log that it read the path, and open the Logs tab.

Next steps

Configure processes

Add web, worker, cron and job processes to a service, set commands, replicas, resources and health checks, and stop, start or restart a service.

Control deploy order

Make a service's deployments wait for the services and databases it depends on, with the Deploy after list or depends_on in nebula.toml, and read what you see while a deployment waits.

On this page

Before you beginSet a release commandWhat happens at a deployMount a variable as a fileVerifyNext steps