Settings

This page shows an administrator how to set up Deployment Manager so it can work. It covers the Settings tab, the first administrator, and the settings that control what data leaves the tool.

What you do here

This section lists the tasks on this page.

Enter the credentials for GitHub, Harbor, Jira and SMTP on the Settings tab.
Understand how service contracts reach the tool. A contract is a file that says what one service needs.
Create the first administrator.
Set the environment variables when you install Deployment Manager itself.
Decide what the in-app assistant may see.
Understand how a release arrives from CI/CD Manager.

The Settings tab needs the role global_admin. For roles, see People and roles. See What is Deployment Manager for the tool itself.

To change a credential:

Open the Settings tab.
Fill in the fields of the section you need.
Press Save Settings.

Settings

This section lists the credentials in the Settings tab and what each one enables.

The Settings tab (global_admin) holds the credentials the tool needs. The table shows what each one enables.

Section Fields Unlocks

Section	Fields	Unlocks
GitHub	Organisation, token	Reading each service’s contract from its repository. See Service repositories and contract sync.
Harbor	URL, username, password	Looking up image tags for a service when a bundle is generated. It is also used to pull images into an offline bundle, and to pull images on the Test install servers. It is never sent to a customer’s server. A server that pulls from the registry must be signed in to it already. See the image-pull failure.
Jira	URL, account email, API token, project key, issue type, Assign reports to, and the project’s required fields (press Read from Jira)	Filing a bug from the panel of the in-app assistant (see The in-app assistant). URL, token and project key must all be set. Without them, no bug can be filed.
SMTP	Host, port, security, username, password	Sending the sign-in code and link that every login sends. Without it, `FLASK_DEBUG` mode shows the code on screen instead. This is a fallback for local development. It does not replace SMTP in production.

GitHub

Organisation, token

Reading each service’s contract from its repository. See Service repositories and contract sync.

Harbor

URL, username, password

Looking up image tags for a service when a bundle is generated. It is also used to pull images into an offline bundle, and to pull images on the Test install servers. It is never sent to a customer’s server. A server that pulls from the registry must be signed in to it already. See the image-pull failure.

Jira

URL, account email, API token, project key, issue type, Assign reports to, and the project’s required fields (press Read from Jira)

Filing a bug from the panel of the in-app assistant (see The in-app assistant). URL, token and project key must all be set. Without them, no bug can be filed.

SMTP

Host, port, security, username, password

Sending the sign-in code and link that every login sends. Without it, FLASK_DEBUG mode shows the code on screen instead. This is a fallback for local development. It does not replace SMTP in production.

Service repositories and contract sync

This section explains where service contracts come from and how they are updated.

Deployment Manager builds a bundle from one contract per service. A contract says what the service needs and what it publishes. It also says which other services it must share a host with, and which ones it must not share a port with. The tool pulls these contracts from a configured list of service repositories. It uses GitHub and the token in Settings. During development, a local directory of contracts can replace GitHub.

A sync pulls the newest contract from every configured repository and validates each one. It then replaces what the tool currently knows, before anything is generated from it. Anyone with the role user or higher can start a sync by hand, through the API (POST /api/compose/sync-contracts). There is no button for it on screen. A sync also runs by itself on a fixed interval. So a contract changed in a service’s own repository reaches Deployment Manager without anyone having to ask for it.

The admin list, and how the first admin is created

This section explains the admin list and how the first administrator gets the top role.

The admin list is a list of email addresses kept in Settings. It has two effects. When an address on that list signs in for the very first time, it gets the top role, global_admin, at once. And the header shows an Admin badge for every address on the list. The badge opens no screen. What a person can open depends only on their role. See People and roles for what that rank means and how roles are granted later. Adding an address to the list has no effect on an account that has signed in before. Its role is then stored on its own account record. Only another global_admin can raise it from there.

A fresh installation comes with one address already on the list. The first sign-in as that address makes that account the first administrator. No other setup is needed. The sign-in flow itself is enough. A development instance may have no mail server configured. In that case the sign-in screen shows the code directly and does not mail it. This exists only so that a first admin can be created without a mail server.

A well-known development password exists. It lets you sign in quickly as a fixed test identity during local development. It does not give administrator rights, on purpose. That identity is left off the admin list on purpose. The password is public in the source code. The tool holds customers' SSH credentials and can deploy to their production servers. If that password gave full admin control, anyone who read one line of the code could administer this tool. That risk is not acceptable. If every administrator route refuses that identity with a permission error, the design is working correctly. It is not a defect.

The admin list is read only when an address signs in for the first time. It never changes an account that already exists. To recover a lost last administrator, add an address that has never signed in to the admin list in the stored settings. Then sign in with that address. This is a manual action on purpose, and it should be rare.

Environment variables

This section lists the environment variables of Deployment Manager, grouped by what they enable.

These variables are set by the person who deploys Deployment Manager itself, in its Docker image or Kubernetes manifest. An operator does not set them inside the tool. Some are marked foot-gun. A foot-gun is a setting that has caused a real incident. Read those entries in full before you change them.

Identity and sign-in

Variable Effect

Variable	Effect
`APP_URL`	The URL used in sign-in emails. It is also the origin that Test install’s in-browser shell checks connections against.
`AUTH_ALLOWED_DOMAIN`	Limits who may request a sign-in code at all. Everyone else is refused before a mail is sent.
`APP_VERSION`	The build written into every journal row, so a defect can be linked to the version that caused it. If it is unset, that column is blank. It does not show a placeholder word, because a placeholder would sort and group as if it were a real version.

APP_URL

The URL used in sign-in emails. It is also the origin that Test install’s in-browser shell checks connections against.

AUTH_ALLOWED_DOMAIN

Limits who may request a sign-in code at all. Everyone else is refused before a mail is sent.

APP_VERSION

The build written into every journal row, so a defect can be linked to the version that caused it. If it is unset, that column is blank. It does not show a placeholder word, because a placeholder would sort and group as if it were a real version.

The database

Variable Effect

Variable	Effect
`POSTGRES_PASSWORD` (and the matching host/port/user/database, or one full `DB_URL`)	Foot-gun. Required for every part of the tool that works with an installation. This includes topologies, generating a bundle, deploying, and the journal. If it is unset, the app still starts. But every one of those actions answers with a service-unavailable response. The first time this happens, it looks as if the whole tool is broken, not as if one setting is missing.

POSTGRES_PASSWORD (and the matching host/port/user/database, or one full DB_URL)

Foot-gun. Required for every part of the tool that works with an installation. This includes topologies, generating a bundle, deploying, and the journal. If it is unset, the app still starts. But every one of those actions answers with a service-unavailable response. The first time this happens, it looks as if the whole tool is broken, not as if one setting is missing.

The service catalogue

Variable Effect

Variable	Effect
`COMPOSE_TEMPLATES_DIR`	Foot-gun. Overrides the bundle templates and compose fragments that ship with the tool. Leave it unset. That is the correct default, and every install then uses what is built in. If it points at an old checkout, a generated bundle can contain an old template. A customer’s server can reject that template with an error message this build of the tool does not recognise. The deploy then reports a failure with no matching explanation. Set it only when you have checked that the checkout is ahead of what ships with the tool.
`COMPOSE_CONFIGS_ROOT`	Foot-gun, of the same kind as the one above. Overrides the configuration trees for each service (XML, properties, keystores, SQL, Dockerfiles). A generated bundle mounts these into each container. If it is unset, the trees ship with the tool. Setting it silently replaces them with the operator’s own checkout. Nothing on screen says this happened.

COMPOSE_TEMPLATES_DIR

Foot-gun. Overrides the bundle templates and compose fragments that ship with the tool. Leave it unset. That is the correct default, and every install then uses what is built in. If it points at an old checkout, a generated bundle can contain an old template. A customer’s server can reject that template with an error message this build of the tool does not recognise. The deploy then reports a failure with no matching explanation. Set it only when you have checked that the checkout is ahead of what ships with the tool.

COMPOSE_CONFIGS_ROOT

Foot-gun, of the same kind as the one above. Overrides the configuration trees for each service (XML, properties, keystores, SQL, Dockerfiles). A generated bundle mounts these into each container. If it is unset, the trees ship with the tool. Setting it silently replaces them with the operator’s own checkout. Nothing on screen says this happened.

Offline image bundles

Variable Effect

Variable	Effect
`IMAGE_BUNDLE_DIR`	Where a finished offline bundle is stored until it is downloaded or expires. An offline bundle is an archive that carries its own container images, for a site with no registry access. In a container deployment, this must be a persistent volume. Otherwise the archive disappears when the pod restarts. The download link on screen then stops working without any message.
`IMAGE_BUNDLE_TTL_DAYS`	How long a finished offline bundle stays downloadable before it is deleted.
`IMAGE_BUNDLE_MIN_FREE_GB`	The minimum free disk space for a build. Below it, a build refuses to start. This prevents the disk from filling up during a build.
`IMAGE_BUNDLE_PLATFORM`	The CPU platform the pulled images must be for. Customer servers are x86. An image pulled for the wrong platform installs without an error. It then fails at start-up with an architecture-mismatch error. That error gives no hint of the real cause.

IMAGE_BUNDLE_DIR

Where a finished offline bundle is stored until it is downloaded or expires. An offline bundle is an archive that carries its own container images, for a site with no registry access. In a container deployment, this must be a persistent volume. Otherwise the archive disappears when the pod restarts. The download link on screen then stops working without any message.

IMAGE_BUNDLE_TTL_DAYS

How long a finished offline bundle stays downloadable before it is deleted.

IMAGE_BUNDLE_MIN_FREE_GB

The minimum free disk space for a build. Below it, a build refuses to start. This prevents the disk from filling up during a build.

IMAGE_BUNDLE_PLATFORM

The CPU platform the pulled images must be for. Customer servers are x86. An image pulled for the wrong platform installs without an error. It then fails at start-up with an architecture-mismatch error. That error gives no hint of the real cause.

Deploying to a customer’s servers

Variable Effect

Variable	Effect
`DEPLOY_DRAIN_TIMEOUT`	How long Deployment Manager waits, when it shuts down, for an install that is already running on a customer’s servers. After this time it gives up. The tool runs as one process. So a normal restart would otherwise kill a deploy in progress. Instead, on shutdown it refuses new deploys. It keeps running until this timeout ends or the deploy finishes, whichever comes first. Foot-gun in a container deployment specifically. Several other timeouts sit above this one: the container platform’s own grace period, the process supervisor’s stop wait, and the web server’s own graceful-timeout. Each one ends in a hard kill on its own schedule. The smallest of all of them decides in practice. So raising only this one changes nothing unless you raise the others to match.
`DEPLOY_SOURCE_ADDRESSES`	The address or addresses shown to an operator as "what a customer’s firewall needs to allow". The tool needs this to reach a server over SSH. If it is unset, the tool uses the connecting address that a server last reported. Inside a container platform, this is usually not the address the customer’s firewall sees. The reason is network address translation on the way out. In that kind of deployment, set it explicitly to the platform’s known outbound address.

DEPLOY_DRAIN_TIMEOUT

How long Deployment Manager waits, when it shuts down, for an install that is already running on a customer’s servers. After this time it gives up. The tool runs as one process. So a normal restart would otherwise kill a deploy in progress. Instead, on shutdown it refuses new deploys. It keeps running until this timeout ends or the deploy finishes, whichever comes first. Foot-gun in a container deployment specifically. Several other timeouts sit above this one: the container platform’s own grace period, the process supervisor’s stop wait, and the web server’s own graceful-timeout. Each one ends in a hard kill on its own schedule. The smallest of all of them decides in practice. So raising only this one changes nothing unless you raise the others to match.

DEPLOY_SOURCE_ADDRESSES

The address or addresses shown to an operator as "what a customer’s firewall needs to allow". The tool needs this to reach a server over SSH. If it is unset, the tool uses the connecting address that a server last reported. Inside a container platform, this is usually not the address the customer’s firewall sees. The reason is network address translation on the way out. In that kind of deployment, set it explicitly to the platform’s known outbound address.

Test install (the disposable-server sandbox)

Variable Effect

Variable	Effect
`LAB_RUNNER_URL`	Address of the separate service that owns the disposable servers. Test install creates and deletes these servers through it. If it is unset, the Test install screen says: "Test installs are not set up on this Deployment Manager". Nothing can be started there.
`LAB_RUNNER_JWT_SECRET`	The secret this tool and that separate service share. Each side uses it to check that the other side’s requests are genuine. It must be the same value in both places. A mismatch makes Test install fail, not disappear. That is a different symptom to look for.

LAB_RUNNER_URL

Address of the separate service that owns the disposable servers. Test install creates and deletes these servers through it. If it is unset, the Test install screen says: "Test installs are not set up on this Deployment Manager". Nothing can be started there.

LAB_RUNNER_JWT_SECRET

The secret this tool and that separate service share. Each side uses it to check that the other side’s requests are genuine. It must be the same value in both places. A mismatch makes Test install fail, not disappear. That is a different symptom to look for.

Secrets storage

Variable Effect

Variable	Effect
`DEPLOYMENT_SECRETS_KEY`	Foot-gun. The key that encrypts every stored SSH credential and Test install keypair. If it is missing, none of those can be saved at all. If it is changed after credentials were stored, all of them become unreadable at once. Nothing reports this on its own. The failure shows only the next time a deploy or Health tries to use one. This value must stay the same for the whole life of the deployment.

DEPLOYMENT_SECRETS_KEY

Foot-gun. The key that encrypts every stored SSH credential and Test install keypair. If it is missing, none of those can be saved at all. If it is changed after credentials were stored, all of them become unreadable at once. Nothing reports this on its own. The failure shows only the next time a deploy or Health tries to use one. This value must stay the same for the whole life of the deployment.

Releases

Variable Effect

Variable	Effect
`RELEASE_PUSH_SECRET`	The shared secret CI/CD Manager uses to sign a release push. See How a release arrives from CI/CD Manager. It is different from every credential in Settings. It is not a customer’s or a vendor’s password that an operator changes on screen. It proves to this tool that the push comes from our own build pipeline. So it is set here, not in Settings.

RELEASE_PUSH_SECRET

The shared secret CI/CD Manager uses to sign a release push. See How a release arrives from CI/CD Manager. It is different from every credential in Settings. It is not a customer’s or a vendor’s password that an operator changes on screen. It proves to this tool that the push comes from our own build pipeline. So it is set here, not in Settings.

The in-app assistant

This section describes the in-app assistant, what it can see, and its limits.

The assistant answers questions an operator asks while working. Examples: what a variable means, which services a topology needs, why a preflight check failed. It answers from a document corpus, plus what it is told about the tool’s own current state.

What it can see on every question:

the installations that exist, their customers, hosts and services.
the shape of the installation the question is about.
the values an operator entered for that installation’s variables.

It never sees a secret. The store it reads from holds no secrets by design. A value whose name looks like a credential is also withheld, whatever it contains.

Two switches decide what leaves the app when someone asks a question. Each answers a different question:

Variable Controls

Variable	Controls
`ASSISTANT_SHARE_STATE`	Whether installation names, customer names and hostnames leave the app at all, on any question. If it is off, the assistant can still explain the product in general. It cannot answer anything about a specific installation.
`ASSISTANT_SHARE_VALUES`	Whether the values an operator entered are sent along with that state. If it is off, the assistant knows an installation exists and what it is made of. It does not know what any of its variables are set to.

ASSISTANT_SHARE_STATE

Whether installation names, customer names and hostnames leave the app at all, on any question. If it is off, the assistant can still explain the product in general. It cannot answer anything about a specific installation.

ASSISTANT_SHARE_VALUES

Whether the values an operator entered are sent along with that state. If it is off, the assistant knows an installation exists and what it is made of. It does not know what any of its variables are set to.

A value is recognised as a credential in two ways, in this order:

The contract of the service that owns it marks it as a credential. Such a value never leaves the app.
Its name looks like a credential, for example it contains pass, pwd, secret or token. This check runs every time.

If no contract can be read at all, a wider name pattern is used. It also hides key and keystore names. So a database outage makes the assistant less informative, but never less careful. Any value longer than a couple of hundred characters is shortened in every case. A certificate or a key does not belong in a question.

The assistant needs two settings: ASSISTANT_URL and ASSISTANT_CALLER_TOKEN. If either one is unset, the assistant does not appear on screen at all. A control that can only fail is worse than no control.

Two limits explain some answers an operator can see:

Everything in one question shares one size limit. This includes the operator’s words, an attached log, and the live state above. The typed question is cut to 4000 characters. A long log is cut to fit, and its end is kept. A question that is still over the limit is refused. This is also why the panel’s own probes limit their output.
Answers in progress are limited per worker. When the limit is reached, the next question is told that the assistant is busy and to try again in a few seconds. The reason: an answer holds a worker thread for its whole life. Those threads are shared with the deploy stream and Test install. Protecting an install in progress comes first. Setting the limit to zero turns streaming off. It does not refuse questions. So nobody is told to "try again shortly" about a setting that will never change.

Every answer of the assistant has a Report a bug button. It writes a report from the conversation. If a log or diagnostics file was sent with that answer, the file goes on the ticket too. It uses the Jira project configured in Settings. It never files anything until the operator reviews and confirms the report.

How a release arrives from CI/CD Manager

This section explains how CI/CD Manager sends releases to Deployment Manager, and its limits.

CI/CD Manager pushes a finished release into Deployment Manager when it is published. So an operator who builds an installation gets real, current version numbers. They do not copy them by hand from another screen. The push is checked as a machine call, with RELEASE_PUSH_SECRET above. It does not depend on anyone’s own sign-in session.

Pushing the same release again does no harm. An identical push changes nothing. A changed push replaces the earlier one and does not create a duplicate. What comes back to CI/CD Manager is not permission to install. It says which parts of the release Deployment Manager recognises in its own service contracts, and which parts it does not. So a gap in coverage is visible when a release is drafted. It is not found later during an install.

Coverage is measured against the contracts this instance has synced. On an instance where the contracts were never synced, a release correctly reports that it covers nothing. Check that the contracts are in place before you treat a coverage report as a finding about the release. A release never names a few of the services this tool knows. They come back every time as "no version given". That is correct, not a gap.

The push does not check that the images exist. A successful push means the release was recorded. It does not mean its images can be pulled. That failure appears later, on the customer’s server.

This link fails without any message. Nothing in the channel retries after a pause. A push can fail for any reason other than two pushes colliding. Such a push is not sent again. Nothing stores the fact that it failed. If a release is missing from the wizard’s picker, push it again from the release itself. Nothing will tell you it is missing.

After it is published, the release’s version numbers are offered in the installation wizard. You can use them to fill in the version of every service in one step. They are grouped by product line.

Three things about that step decide how much you can trust it:

It fills, it never decides. Every version box stays editable afterwards. The note gives two counts: how many versions were filled from the release, and how many services the release does not name. Without this, a prefilled form looks like a finished one. Deselecting the release does not undo the fill. The note says so.
The releases are grouped by product line, not filtered to one. An installation here records a topology and its values. It has no product line of its own. So the operator, not the tool, makes sure that one line’s installation does not get another line’s versions. Read the group heading.
A service can show no version after you apply a release. Usually the release named that service with a moving version, not a fixed one. The version picker does not select a moving version, on purpose.

If the picker does not appear at all, the release list could not be fetched or is empty. The step then hides the picker. The wizard’s own check for empty versions still decides whether the operator may continue.