Step 2. Create an installation

An installation is one customer’s install. It connects a topology to the customer’s real servers. This page shows how to create an installation. It also explains the installation card and its actions.

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

What an installation is

This section explains the difference between a topology and an installation.

  • A topology says which services to install, and which server each service runs on. See Step 1. Choose a topology.

  • An installation uses that topology for one customer. It holds a real address for each server, and the values that every service needs.

Several installations can use one topology. Each installation has its own values, its own SSH access and its own history. It does not depend on the others.

Each installation is a card on the Installations tab. The tool does not delete or replace it when its topology changes. See What "behind" means, and how to fix it.

To update an installation that already runs at a customer site, see Update an existing installation.

Before you start

This section lists what you need before you create an installation.

  • An account with the user role or higher.

  • The name of the topology to use. See Step 1. Choose a topology.

  • A short name for the installation, for example acme-prod.

  • The address that the customer’s users will type in their browser.

  • An address for each server in the topology. The servers must reach each other with these addresses.

Do not type SSH passwords in the wizard. The tool asks for them later, at deploy. See SSH access: which installations this tool can reach.

Steps

This section shows how to create an installation. The wizard has four steps: Topology, Instances, Variables and Review & Generate.

  1. Open the Installations tab.

  2. Click + New Installation.

  3. On Topology, type the Environment name, for example acme-prod.

  4. Type the Customer, for example Acme Corp. This field is optional.

  5. In Topology, pick the topology.

  6. In Installation, keep New — these servers are empty. For a site that already runs our product, see Update an existing installation.

  7. Click Next →.

  8. On Instances, type the address in VIP — one address for the whole installation. This is the address users type in their browser, for example portal.customer.net.

  9. Type an address in the box for each server, for example acs1.customer.net. The label under each box shows Runs: and the services on that server.

  10. If the topology has host groups behind a load balancer, type the load balancer’s address for each group. See the load balancer.

  11. Click Next →.

  12. On Variables, fill in the values. See Step 3. Fill in the variables.

  13. Click Next →.

  14. On Review & Generate, check the summary.

  15. Click Create installation.

To go back one step, click ← Back. To leave the wizard, click ← Back to list. The wizard saves an unfinished draft for you. You see it above the list of installations.

The server addresses must work from the servers, not from your browser. To check a name, run this command on the server:

getent hosts acs1.customer.net

It prints the address. If the server cannot find the name, it prints nothing. An IP address needs no check.

What you see

This section describes the installation card and what it shows.

The card and its actions

This section lists the actions on an installation card.

  • If your role does not allow an action, the action is hidden.

  • If your role allows it, but you have no write access to this installation, the action is greyed out. The card says how to ask for access. See Asking for access to an installation.

  • If an action needs something that the installation does not have yet, the action is muted. The card then shows the reason. See Why an action is muted.

Action What it does Reaches a customer server? Minimum role

Deploy

Sends the bundle to every connected server and installs it. It shows progress live. Setting up SSH access is the first step of a deploy. If a credential is missing, the panel opens the access step itself. See Step 6. Deploy.

Yes

user

Download

The bundle as a .zip, for a site that someone installs by hand instead of over SSH. See Step 4. Create the bundle.

No

user

Variables

Opens a choice. In Deployment Manager edits the values that this tool stores. Nothing changes on any server until a Deploy follows. On the server edits the .env file on a server directly. It is offered after the installation was delivered and SSH access is stored. When the installation is behind, the choice is skipped and the values open directly. See Step 3. Fill in the variables.

Only with On the server

user

Bind servers

Opens the steps at Instances, so you can connect a server to each slot of the topology.

No

user

Health

Asks every connected server, live, what its containers are doing now. See Step 7. Check that it works.

Yes

user

Diagnostics

Collects one file for each server, to attach to a ticket. See Step 7. Check that it works.

Yes

user

Test install

Runs the whole install as a practice run on temporary servers. This tool creates and removes them. It never uses a customer’s servers, and never the servers of this installation. See Step 5. Test the bundle.

No (servers of its own making)

user

Delete

Removes the installation and everything recorded for it. See Deleting an installation.

No

support_admin

One action on each card has the solid, primary style:

  • Bind servers, when a slot of the topology has no server, or a server has no slot.

  • Variables, when the installation is behind. Then Deploy and Download are refused, and only Variables can fix it.

  • Download, when no servers are connected.

  • Deploy in every other case.

The shared demo installation has no primary action.

Install stages on the card

This section explains the five steps that each card shows: Hosts bound · Variables · Bundle generated · Delivered · Installed.

The tool works out all five steps again each time it shows the list. You cannot set a step by hand. A step changes only when the data behind it changes. For example, if you remove every connected server, the first step opens again.

Each step checks something narrower than its name says:

Step What it actually checks

Hosts bound

At least one server is connected. If you save an installation with an empty server list, this step opens again without a message, and Deploy is muted.

Variables

At least one value is stored. It does not check that all values are present. A green Variables step does not mean that the tool can build the installation. The refusal at Download or Deploy is the real check. It names what is missing.

Bundle generated

A generation was recorded. This includes a generation that failed part-way. Do not read this step as "a good bundle exists". Read Delivered and the failure line.

Delivered

The bundle left this tool. A download counts the same as a successful deploy. A download of the offline archive also counts. So this step does not prove that the customer received anything.

Installed

Someone said so, or a deploy from here saw it. See below.

Installed is a claim that an operator makes. The card offers Mark installed after a bundle is delivered. It records who made the claim and when. If you marked the wrong card, click Withdraw. This removes the claim completely, including the name. An open step means "nobody has said so yet". It never means "not installed".

After a clean deploy from this tool, the claim is made for you. The tool records it as observed, not as a person’s statement. You do not need to press Mark installed after a green deploy. If a card shows no claim after such a deploy, this is a gap in the records. It is not a failed install.

About half of customer sites are installed from a bundle that someone carries to the site. This tool cannot reach those sites. That is why Installed is a claim.

Two ways an installation goes out of date

This section explains two signals on the card. The fix for both is the same: deliver again.

Signal What it means

A newer bundle exists than the one that was installed

Someone generated or delivered a bundle after the installation was marked installed. The card says Newer bundle not installed. Or someone changed the topology after that. The card says Topology changed since install. Either way, the site runs something older. The tool does not remove the claim. Only a person removes a claim. Generating a bundle without sending it also raises this signal.

Edited here, not yet on the servers

Someone changed a value, an image version or a load-balancer address in this tool after the last delivery. The servers still run the previous configuration.

Two things do not raise the second signal:

  • renaming an installation or editing its notes;

  • saving the same values again.

One thing also does not raise it: changing which servers are bound. After you connect a different host, always deploy again, whatever the card says. The old host still runs the previous install. Nothing here removes it.

If the tool cannot read a date at all, it raises both signals.

SSH access: which installations this tool can reach

This section explains SSH access. Deploy and Health work on a customer’s servers. Both need an account on every connected server. Without stored access, this tool cannot reach the installation. Then you use a bundle. Someone installs it at the site by hand, and deploy.sh does the work. See Step 4. Create the bundle.

The card shows how many servers have stored access:

Shown Meaning

3/3 (all bound servers)

Every connected server has stored access. Deploy and Health run normally.

Partial, e.g. 1/3

A warning, not a success. Health and Diagnostics are muted. Pressing either one opens the access panel instead. Deploy is not muted: it asks for the missing access as its first step.

Not set

No access is stored for any server. Health and Diagnostics are muted. Deploy is not muted: it asks for access as its first step. Or someone carries the bundle to the site by hand.

\—

No servers are connected yet. Then Deploy, Health, Diagnostics and Test install are muted until you bind servers. Or the installation’s record is older than the SSH-coverage feature and has no count. Then nothing is muted.

To open the access panel, you need the user role and write access to this installation. You have write access if you created it, if you hold a grant, or if you are a support_admin or higher. The panel stores one username and one password or private key for each server.

  • The tool encrypts the secret before it saves it. The secret belongs to that installation and server only.

  • The tool never shows the secret again. To replace it, enter it again in full. The panel tells you this.

  • The tool never asks for credentials while you create an installation. The wizard saves drafts as plain text. A password typed there would end up in that draft.

What the firewall must allow

This section explains the firewall rules that a deploy needs. The access panel shows them next to the credentials. You can send the text to the customer’s security team as it is. The Copy button copies both directions in one press.

Inbound: to the customer’s servers, from this application. The servers must accept SSH (TCP 22) from this application. The panel shows this address at one of three levels of certainty:

Certainty What is shown

Configured

The address or addresses that an administrator set (DEPLOY_SOURCE_ADDRESSES). See Deploying to a customer’s servers. This is the strongest answer.

Observed

No address is configured. But a server of this installation already saw this application connect. The panel shows that server and the date. The address can change after a restart or a move of this application. If the date is old, confirm the address first.

Neither

Nothing is configured and nothing is observed yet. The panel says so. It names this container’s own address, but only to tell you not to use it. Network address translation almost always replaces it before it reaches the customer’s firewall.

Outbound: from the customer’s servers, to a registry. The servers must download every image that this installation uses. The panel lists those registry hosts, grouped by host and port. Each entry names the services that need it. Two installations can list different hosts.

  • Hosts of our own registry are marked vendor. Every other host is marked external. If no Harbor URL is set in Settings, no host is marked, and the panel says so.

  • A service built on mysql or ejabberd also needs its base image. Otherwise the build fails, and the error does not mention the registry.

  • A Docker Hub entry has its own warning. Docker Hub uses a second hostname for sign-in, and a CDN for image layers. So allowing only the host named here is not enough.

Not needed. The customer’s servers never contact this application. A deploy only pushes, over SSH. No firewall rule is needed in that direction.

When the hosts cannot be listed yet. Some services may have no image version yet. Then the panel says so. It gives the same reason that a Generate refusal would give. It does not show an empty list.

No route to any registry. About half of customer sites have none. For those sites, use the offline bundle. It carries its own images. Then the servers need no registry, and deploy.sh does not ask about it. See Offline installs.

What this tool holds and what is on the server

This section explains how to compare what this tool stores with what is on the servers. There is no single screen and no "diff" to open. Use one of these four checks:

To find out Use

What is running right now

Health: the list of containers on each server. It shows what exists, not what is missing. See Health.

What is already in the install directory before a deploy

The deploy panel checks each server before the deploy. It shows whether the directory is empty, holds this installation, holds another installation, or could not be read. It also shows how many settings the existing environment file holds. If the number is not zero, the deploy changes a live configuration.

Which settings a server’s environment files have

The installation’s environment editor. It lists the files by name and the names of the settings in each file. It never shows a secret’s value. To be sure of a password, set it.

Everything else, after the fact

Diagnostics. See Diagnostics.

If you edit a non-secret value directly on a server, the tool also saves it in its own records. So the next deploy does not undo your fix. Two kinds of value cannot be saved back: values that this tool computes, and values that no service declares. For those, the tool tells you. The next deploy will undo those fixes.

Good to know

This section covers access, deleting and changing server addresses.

Asking for access to an installation

This section explains who can change an installation.

  • Any signed-in user can read any installation. One exception: a colleague’s practice installation from training. Only a support_admin or higher sees it.

  • To change an installation that you did not create, you need a grant. You do not need access to ask for access.

  • You can request a grant and add a reason. You can have one open request per installation at a time.

  • To grant a request, or to grant access directly, you need the support_admin role.

  • A person who holds a grant cannot give access to someone else.

  • A revoked grant stays on the record as revoked. The record shows who asked, who decided and when.

For roles, see People and roles.

A site that this tool did not create

This section explains why the tool cannot take over an existing site. There is no import.

Some sites were installed by hand from a bundle, or by an earlier tool. For those, create the installation here from the start. Expect the deploy to refuse. Before it copies anything, the tool checks the install directory. It refuses when the directory already holds an install without a server-id file, or an install for a different server. Nothing is changed then.

For a record that has no owner, a support_admin sees Make this installation belong to and Set owner. This only gives an owner to that record. It does not take over a site. To let a colleague work on an installation, grant write access. See Asking for access to an installation.

Deleting an installation

This section explains what deleting does. You need the support_admin role. Deleting is the most destructive action on a card.

Deleting removes the installation and everything recorded for it:

  • its connected servers;

  • its stored variable values;

  • its deployment and delivery history;

  • its test-install runs;

  • its offline-bundle builds;

  • its encrypted SSH credentials.

There is no undo and no export. Two things stay:

  • the journal. It keeps the installation’s name. You can still see who had write access to that customer’s production, and what they did.

  • the write-access grants, for the same reason.

Deleting does not remove anything from the customer’s servers. The containers, the install directory and the databases keep running. The tool then has no record of that install. It will refuse to deploy over it (see A site that this tool did not create).

Nobody can delete the shared demo installation that the training course uses.

Changing the address of a server

This section explains what happens when you change a server’s address.

Each server slot of the topology is connected to one address. The slot is the identity, not the address. Stored SSH credentials, install directories and the deploy history belong to the slot.

So after you change an address, the next deploy, Health, Diagnostics and every retry go to the new machine. They use the credential stored for that slot. The old machine keeps running the installation. Nothing here mentions it again.

After you change an address:

  1. Check the stored credential for that slot again.

  2. Deploy again.

  3. Decide what to do with the old host.

If the topology no longer uses a slot, its credential is hidden but not deleted. If you add a slot with the same name again, the old credential comes back. Remove it if you do not want that.

If something goes wrong

This section explains muted actions and installations that are behind.

Why an action is muted

This section lists the reasons why a card mutes an action. The card prints the reason. These are the sentences that the card shows:

Reason shown What it mutes

No servers are bound to this installation yet — Deploy, Health and Diagnostics have nowhere to run. Bind servers first.

Deploy, Health and Diagnostics

No servers are bound to this installation yet — there is nothing to install on the test servers. Bind servers first.

Test install

The topology has new services this installation has no values for. Deploy and Download are blocked until Variables is filled in.

Deploy and Download

Not every server has SSH access stored. Deploy and Health stop at the first server without it.

Health and Diagnostics (Deploy opens the SSH panel as its first step instead)

The topology changed: a host here has no server, or a server here has no host. Deploy, Download and Test install are blocked.

Deploy, Download and Test install

No SSH access is stored for these servers. Deploy and Health cannot reach them without it. Set up SSH access, or carry the bundle to site and install it there by hand.

Health and Diagnostics (Deploy opens the SSH panel as its first step instead)

Health and Diagnostics stay muted when SSH access is missing. Both only read a server. Deploy can set up access for you. Health and Diagnostics cannot.

What "behind" means, and how to fix it

This section explains what "behind" means and how to fix it. An installation is behind when both are true:

  • its topology changed after the installation was last saved;

  • the installation has no answer yet for something that the topology now needs.

Usually this is a variable or an image version for a new service. You did not cause this. It happens when someone changes a shared topology.

The fix is always the same:

  1. Click Variables on the card.

  2. Choose the versions.

  3. Fill in the values.

A card that is behind shows the number of missing items. Deploy and Download are muted until you fix them (see Why an action is muted). Health, Diagnostics and Test install still work. None of them builds a bundle. So you can still check a live site. A service that the topology removed keeps its stored values. You can see them and remove them in one action.

A third answer: "the check could not run." The card shows this, and it blocks nothing. It happens when:

  • The topology of this installation is no longer stored, or cannot be read.

  • No service contract is stored for a service in the topology. Usually the service was added before the contracts were synced.

  • Two services in the topology claim the same role.

Right after the application restarts, every installation shows this answer for a few seconds. Then it goes away. Wait. Do not change any settings.

These five cases do not make an installation behind:

  • a service that is built on the target server, not downloaded from a registry;

  • a service whose values all have defaults;

  • a service that the customer runs themselves, which has no container here;

  • a new secret, which the tool never stores and always asks for at install time;

  • a variable for the other database vendor.

An installation that is not behind can still be refused at Download. The tool checks every required value only when it builds a bundle. The refusal names the values.

A second signal can appear next to it. It blocks nothing. It is a load-balancer address that no longer applies. Someone renamed the host group that the address was stored under. The addresses then change back to each server’s own address. See the load balancer.

For other problems, see When something goes wrong.