Step 3. Fill in the variables

This page shows how to fill in the Variables screen. It says where each value comes from, so you know what you must type. It also says why the tool can generate some passwords and not others.

A variable is one setting that a service needs, for example a port or a database address. A secret is a variable that holds a password, key or token.

For every variable and what it does, see the Full list of environment variables.

For the other words used here, see Words you need to know. For the whole install, see Install the system at a customer site.

Before you start

This section lists what you need before you fill in the variables.

An installation with a topology and server addresses. See Step 2. Create an installation.
The release to install.
The values that only the customer knows. For example, the address and password of a database that the customer runs.

You see the Variables screen in two places:

Step 3 of the + New Installation wizard. This is before a bundle exists.
The Variables action on the card of an existing installation. Use it when the topology changed and new answers are needed.

In both places, nothing you type here reaches a server. A Deploy must follow.

Steps

This section shows how to fill in the Variables screen.

In Fill versions from a release, pick the release to install. This sets the image version of every service that the release includes. The note next to the picker says which ones. Pick a version by hand for any other service.
Click the Needs input filter. The screen now shows only the services that need a value from you.
Open each service and fill in every empty required field.
Secrets are not filled in here. Their boxes are greyed out. You answer them at deploy: in the Deploy panel, or in deploy.sh at the site. See Secrets: three ways a row is answered.
To find one variable, type its name in Find.
Fix every field that shows a red reason next to it.
Click Next →.

Other controls on this screen:

The filters All, Needs input, Changed and New choose which services you see.
Expand all and Collapse all open or close every service.
↻ Re-read contracts loads the service contracts again. It appears only when it is needed.

What you see

This section explains the fields on the screen and where their values come from.

Where a value comes from

This section lists the three sources of a value. For a standard install, most fields need no typing. Only one of the three sources is you:

Source	What it means
The service’s own default	The value the service ships with. It comes from the service contract. The screen shows it without a mark. The screen marks a field only when its value is different from the shipped value.
Derived from the topology	Calculated from the servers a service runs on and how they connect. Examples: a database host, a cluster member list, a service’s own address. You cannot type over this value. It is calculated again each time the bundle is generated.
Typed by the operator	Entered by hand. There are two reasons. Nothing else can supply it (for example, the address of the customer’s own database). Or the default was changed on purpose for this site.

Source

What it means

The service’s own default

The value the service ships with. It comes from the service contract. The screen shows it without a mark. The screen marks a field only when its value is different from the shipped value.

Derived from the topology

Calculated from the servers a service runs on and how they connect. Examples: a database host, a cluster member list, a service’s own address. You cannot type over this value. It is calculated again each time the bundle is generated.

Typed by the operator

Entered by hand. There are two reasons. Nothing else can supply it (for example, the address of the customer’s own database). Or the default was changed on purpose for this site.

A service that the customer already runs is an example of the third case, for example their own database or their own ClickHouse. This tool installs nothing on that machine. So the topology cannot calculate its address. The field is required, and it has no default.

Secrets: three ways a row is answered

This section explains how the Deploy panel and deploy.sh ask for secrets. The Variables screen does not ask for them.

The Deploy panel asks for each secret once per name. Two services in the same installation can use a credential with the same name. Then they share one answer. This is on purpose. If they really need two different credentials, fix it in the contract. The panel does not ask twice.

A secret’s row offers exactly one of three answers. The service’s own contract decides which one. The screen never guesses from the name.

What the row offers	Meaning
Generate	This tool creates the credential itself. Press Enter (in the installer) or the Generate control (on screen). You get a long random value. Most install-time secrets are this kind.
Use shipped value	The value this credential already has. The contract publishes it. An example is the FT ACS web-service password built into that image. The value is shown in clear text. It is never pre-filled. You can keep it, or replace it if it was changed somewhere else. It is never generated. A random value for an account this tool does not own would lock that account out.
Typed	A value that belongs to something outside this install. Most often it is a database or an SMTP account that the customer runs. Nothing is offered or generated here. A generated value would give an install that fails to sign in.

What the row offers

Meaning

Generate

This tool creates the credential itself. Press Enter (in the installer) or the Generate control (on screen). You get a long random value. Most install-time secrets are this kind.

Use shipped value

The value this credential already has. The contract publishes it. An example is the FT ACS web-service password built into that image. The value is shown in clear text. It is never pre-filled. You can keep it, or replace it if it was changed somewhere else. It is never generated. A random value for an account this tool does not own would lock that account out.

Typed

A value that belongs to something outside this install. Most often it is a database or an SMTP account that the customer runs. Nothing is offered or generated here. A generated value would give an install that fails to sign in.

When the installer finishes its questions, it writes a credentials file next to itself. The file lists every password it set and what each one is for.

The file is never part of the bundle.
This tool does not store it.
After you delete that file, most of those values exist nowhere else.

For this reason, the same step in the Deploy panel does not close until you copy every generated value. If the browser cannot copy, write each value down, then click I wrote them down myself.

Shared values and values for one service

This section explains how values are split between files. An installation has a root environment file plus one file for each service.

These values stay in the shared root file:

a value that every container needs;
a value that more than one service reads under the same name.

A value that only one service reads goes into that service’s own file.

On screen, this means:

A field marked "shared" affects every container on that server when you change it.
A field for one service affects only that service.

The installation’s .env editor shows this split. It lists the root file and each service’s own file separately, each by its own name.

How a value is checked

This section explains how the screen checks a value. Most fields have only a basic type check. When a field has a rule, the rule comes from one of two places:

Inferred from the field’s type and name. A *_PORT field is checked as a port number. A name that looks like an address is checked as a host or IP. A name that looks like a URL is checked as a URL. There are more cases like these.
Set by the service that owns the field. This can be a minimum and maximum, a pattern the value must match, or a comparison with another field of the same service.

Secrets have one more rule: a minimum length. The Deploy panel shows the minimum under the box before you type. It refuses a shorter value. The installer uses the same minimum in a terminal. Two services can ask for the same secret with different minimums. Then the longer one applies.

A refused value stays on screen. The reason is printed next to the field, not in a general error banner. So you always see which field to fix.

What picking a new version changes

This section explains the version comparison. When you choose a release on this screen, the screen compares two versions:

the version you install;
the version this installation was last generated from.

Before anything is saved, the screen shows what changed:

Group	What it means
New variables	This version reads these for the first time. The required ones are marked. Generating refuses if a required one is empty. That refusal has its own sentence. It is separate from the usual "a value is missing" refusal, because nothing here is out of date. It is new.
Now required	These were optional on the version this installation runs. They are not optional any more.
You supply these now	The customer supplies these now, not us.
Fewer values allowed	A value that was allowed on the previous version may not be allowed any more.
Default changed	Shown only when this installation never had its own value for the field. Only then does the new default reach the service. A field that this installation already answered does not change.
No longer used	This version does not read these any more. Nothing is dropped. The value is kept and shown. You decide what to do with it.

Group

What it means

New variables

This version reads these for the first time. The required ones are marked. Generating refuses if a required one is empty. That refusal has its own sentence. It is separate from the usual "a value is missing" refusal, because nothing here is out of date. It is new.

Now required

These were optional on the version this installation runs. They are not optional any more.

You supply these now

The customer supplies these now, not us.

Fewer values allowed

A value that was allowed on the previous version may not be allowed any more.

Default changed

Shown only when this installation never had its own value for the field. Only then does the new default reach the service. A field that this installation already answered does not change.

No longer used

This version does not read these any more. Nothing is dropped. The value is kept and shown. You decide what to do with it.

A variable can move from one service to another between versions. Then it shows as gone from the first service and new on the second. It never shows as unchanged.

In two cases the screen says what happened and does not guess:

This installation has no recorded previous contract. There is nothing to compare with. The comparison works from this installation’s next deploy onward.
A service’s contract at the picked version could not be read. The screen names its variables as not compared.

For the whole upgrade flow, see Update an existing installation.

When a version needs another service

This section covers a service that moves its configuration to another service.

At some version, a service can stop keeping its own configuration files. Another service then keeps them. For example, ftacs did this at version 6.5.2. It moved its configuration into ft-configs-service. This change does not show as a variable. It shows as a service that the topology must include.

If that other service is not in this installation’s topology, the screen tells you before you save. It says:

which service stopped keeping its own files;
at which version;
which service keeps them now.

It also gives you a link to the topology, so you can add that service. Generating a bundle refuses for the same reason. Nothing is built and nothing is sent to any server. This stays true until the topology includes that service.

The screen also names the files that the new version no longer reads. They are not removed from a server that already has them. If someone edits one of them, nothing reads the change.

Good to know

This section explains where your values go, and when they reach a server.

Values that go into a mounted file

This section is about values that go into a configuration file. Most values reach a container through an environment file. A few services read a credential from a mounted configuration file instead. This is a JSON or XML file. It does not understand ${VARIABLE} substitution like an environment file does. You still answer these values on the Variables screen in the same way. The bundle writes each value into the right file. You do not fill in anything extra.

What saving a variable does, and does not do

This section explains when a change reaches a server.

When you save on the Variables screen, this tool updates what it stores. The save does not change anything on a customer’s server. Nothing changes there until you run a Deploy. The screen tells you this. So you can change an answer, come back later and change it again. A live site is not touched until you deploy.

There is a second way to change a value: edit the environment file directly on a server. That writes to the server at once. The change works only after the affected containers restart. This is not the same as Variables. You cannot use one in place of the other. It is part of the installation card. It exists only when servers are bound and reachable.

If something goes wrong

This section explains why the tool does not generate a password.

Why a password is refused, not generated

This section lists why a secret is not generated. There are exactly four reasons. The reason tells you what to type.

A common surprise: the same kind of installation generates a password on one topology and refuses it on another. The reason is the database. One topology says the database is the customer’s own. The other has a database that this tool installs.

Reason What it means What to do

Reason	What it means	What to do
`external`	A service that the customer runs declares this value. So the value belongs to the customer. A value generated here gives an install that cannot sign in.	Ask the customer, or the administrator of that service, for the value it already uses.
`offered`	The contract publishes the value this credential already has. This install does not create it.	Accept the offered value. Or type a new one if it was changed at the source.
`optional`	Nothing requires a value. An empty answer is a real answer. An invented value here would turn on a feature and then fail to start it.	Leave it empty unless you want the feature it controls.
`undeclared`	No service in this installation declares the value.	Nothing to fill in. The row should not need an answer.

external

A service that the customer runs declares this value. So the value belongs to the customer. A value generated here gives an install that cannot sign in.

Ask the customer, or the administrator of that service, for the value it already uses.

offered

The contract publishes the value this credential already has. This install does not create it.

Accept the offered value. Or type a new one if it was changed at the source.

optional

Nothing requires a value. An empty answer is a real answer. An invented value here would turn on a feature and then fail to start it.

Leave it empty unless you want the feature it controls.

undeclared

No service in this installation declares the value.

Nothing to fill in. The row should not need an answer.

For other problems, see When something goes wrong.