Variables and secrets

Each service has its own environment variables. Your app reads its settings and its secrets from them. Ferry gives them to each container when it starts.

ferry env set api LOG_LEVEL=info

Set and remove variablesCopy Anchor Link

ferry env set api LOG_LEVEL=info REGION=eu
ferry env unset api LOG_LEVEL

Saved. Restarting 'api' with the new environment.

A key has 256 characters at most, with no = and no space. A value has 32 KiB at most. All the variables of one service have 256 KiB at most.

See the variablesCopy Anchor Link

ferry env api                  # the own variables of the service
ferry env api --effective      # with the variables of its env groups

The second command shows the merged environment. Ferry merges three layers, and a later layer wins:

1. the variables that Ferry adds: PORT and FERRY_*
2. the variables of the env groups of the service, in the order of the links
3. the own variables of the service

Thus an own variable replaces a variable with the same key from a group.

Keep secret values safeCopy Anchor Link

Ferry has no special type for a secret. A password, a token or a key is an environment variable, the same as other settings.

• The dashboard hides the values. Click Reveal to see them.
• ferry env and the API show the values to each person who has a session or an API token.
• For the password of a datastore, use a reference. Do not copy the password.
• To make a random secret, use openssl:

ferry env set api "SESSION_SECRET=$(openssl rand -hex 32)"

A build also gets the variables, as build secrets. A Dockerfile that Ferry makes keeps them out of the image. In your own Dockerfile, mount the secret in the step that needs it:

RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci

Do not put a secret in an ARG. Docker records the value of an ARG in the history of the image, and each person who has the image can read it.

Share variables with an env groupCopy Anchor Link

An env group is a set of variables with a name. Link it to each service that needs the same values.

ferry env-group create shared LOG_LEVEL=info REGION=eu
ferry env-group link api shared
ferry restart api

The name of a group has 1 to 64 characters: letters, digits, -, _ or ..

In the dashboard, click Env groups in the icon rail.

Connect to a datastore or a serviceCopy Anchor Link

A value can contain a reference. Ferry replaces it with the real value each time a container starts. Thus your app always gets the current address and password. A reference finds a datastore or a service of the environment of the service only. When two environments have a db, the reference of each service finds the db of its environment. The references of an env group follow the environment of each service that uses the group.

ferry env set api 'DATABASE_URL=${{datastore.app-db.connectionString}}'

The containers of api then get DATABASE_URL=postgresql://app_db:<password>@app-db:5432/app_db.

A reference has three parts between ${{ and }}: the kind, the name and the property. The kind is datastore (or db) or service (or svc). The name is the name of the datastore or the service. The property is case-sensitive.

A value can have text around a reference, or many references:

ferry env set web 'API_URL=${{service.api.internalUrl}}/v1'

To write a literal ${{ in a value, write $${{. The value $${{ name }} reaches the app as ${{ name }}.

When a change appliesCopy Anchor Link

Ferry freezes the environment of a deploy when the deploy starts its containers. This is the snapshot. A replacement after a crash, a scale up, a resume and a job use the snapshot of the live deploy. Thus a saved change applies only at the next deploy or restart.

ferry restart api --follow

A restart uses the live image again with the current variables. It does not build. The new instances must pass the health check before the old instances stop.

When a datastore or a target service changes, the containers that run keep the old values. Restart the service to get the new values.

If a reference does not resolveCopy Anchor Link

The CLI checks the syntax before it saves. It also gives a warning for a name that does not exist:

warning: X: reference to unknown datastore 'nope'; deploys fail until it resolves

At the deploy or the restart, Ferry resolves each reference. If one fails, the deploy fails with the status deploy_failed, and the previous deploy continues to answer. The deploy log gives the cause:

Fix the variable with ferry env set. The restart then uses the new value.

Ferry refuses to delete a datastore or a service that other services reference. The error lists the services and their variables. With --force, Ferry deletes it, and the services that reference it fail at their next deploy or restart.