Step 4. Create the bundle

This page shows you how to create the bundle. The bundle is the package with everything needed to install on the customer’s servers. It is one .zip archive.

Before you start

This section lists what must be ready before you create a bundle.

For the product words on this page, see the glossary.

Steps

This section shows how to create the bundle and download it.

  1. Open the Installations tab.

  2. Find the card of your installation.

  3. Press ↓ Download. A dialog opens. Its title is Download and the installation name.

  4. Choose one of the two cards:

    • Configuration only: press ↓ Download. Use this when the customer’s server can reach FT HUB. The archive is a few MB and is ready now.

    • Configuration + images: press Build with images. Use this when the customer’s server cannot reach FT HUB. The archive is several GB. It takes minutes to hours.

  5. Wait for the archive. The configuration-only archive downloads at once. The archive with images is built in the background. See How it is built.

  6. Save the .zip file. Now you can test it (see Step 5. Test the bundle) or carry it to the site.

You do not always need to download. Deploy on the card creates the same bundle and sends it over SSH. See Download versus Deploy.

Right after you create an installation, a dialog asks What would you like to do with it? It offers ↓ Download .zip, Deploy over SSH and Run a test install. You can close it. All three stay on the installation card.

What you see: the files in the bundle

This section lists the files in a bundle. The tool builds the bundle from the installation’s topology, contracts and variable answers. At the root of the archive are deploy.sh, README.md, pull-images.sh and pull-images.ps1. Next to them is one directory for each server bound to the installation. A server’s directory holds:

File / directory What it is

compose.yml

The Docker Compose file for that server. There is one per server, not one for the whole installation. Two servers rarely run the same set of containers.

The configuration trees

Configuration files for each service. The containers use them directly. Examples: application settings, certificates, database init scripts. They are plain files in each service’s own directory. They already contain this installation’s values.

.env

The environment file(s) for that server. There is a root file. There is also one file for each service that needs its own (see dm-variables.adoc#per-service-vs-root). Every value that is not a secret is already filled in. The installer asks for secrets when it runs.

deploy.sh (at the root of the archive)

The installer. It runs on the server. It asks a short set of questions. Then it installs everything in the archive. See What the installer asks.

README.md (at the root of the archive)

A checklist for the whole install. You can follow it with nothing else open. It says what to copy where and what to run. It explains each question deploy.sh asks. It also says what to do if the install stops partway.

The archive is the delivery, not the install. Copy it to the server and run deploy.sh there. deploy.sh copies only that server’s files into the install directory and works there.

Download versus Deploy

This section compares the two ways the same bundle reaches a server.

Action What it does

Download

Creates the .zip and gives it to you. Nothing reaches any server. You decide what happens next. You can copy it by hand, carry it on a USB stick, or send it by email. This is the only way for a site that Deployment Manager has no SSH access to.

Deploy

Sends the same bundle to every bound server over SSH. Then it runs deploy.sh there. You see the progress live in the panel. See the deploy panel.

Download and Deploy create the bundle in the same way, from the same answers. The only difference is who carries it to the server.

Offline installs (no route to the registry)

This section explains bundles for a server that cannot reach the image registry. About half of customer sites cannot reach the registry from the server you install. deploy.sh still needs the container images on the server. Deployment Manager gives you two ways to do this.

What "images inside the archive" means

This section explains what the image list contains. Every bundle, online or offline, has a manifest. The manifest lists every image the install needs, for each server. It has two kinds of image:

  • images pulled from the registry, at the version this installation fixes

  • images that are built on the target machine from a base image

The second kind must be on the list. Without them, the manifest looks complete. But the services that build locally fail.

An offline bundle is the same archive with one images.tar.gz file added for each server. That file holds every image in that server’s part of the manifest. At the site, nothing more needs to be pulled. deploy.sh loads the images from the archive, not from the registry. It also does not ask whether the servers can reach the registry.

How it is built

This section explains how Deployment Manager builds an offline archive.

  1. On the card, press ↓ Download.

  2. On the Configuration + images card, press Build with images.

  3. The build starts in the background. It pulls every image the topology needs from the registry. It packs them into the same .zip.

  4. Watch the progress. It is a real percentage, based on the image sizes. You can close the browser tab. The build continues. The installation’s card keeps showing the progress.

  5. When the build is done, the card shows a link to the archive. The Configuration
    images     card shows Ready and ↓ Download the archive.

Know these four things before you start a build:

  • It refuses to start rather than filling the disk. There is a minimum amount of free space where bundles are kept. Below it, the request is refused. The message gives the actual figure. It tells you to delete an old build or make the volume bigger.

  • A build that cannot fetch one image fails completely. It does not give you an archive with a missing layer. A missing layer is worst to find at a customer site with no internet.

  • One archive is built per server, and each one stands alone. So a layer that two servers share is fetched and stored twice. Plan disk space for the total of all archives.

  • Only one processor architecture is pulled. It is the one customer servers use. An image for the wrong architecture installs with no error. Then it fails at start-up. The error does not show the real cause.

Some problems stop a bundle from being created at all. They are reported at once, before the build starts. You do not wait three minutes into a download to see them.

You can download the finished archive in parts. If the download stops, it continues from where it stopped. This helps over a customer VPN. The archive comes with its checksum. With it you can check the copy you receive.

This build needs nothing from you except registry credentials. They must already be set up in Deployment Manager. It takes much longer than the configuration-only bundle: tens of minutes to an hour for a full topology. The finished archive is a few gigabytes. It is kept for at least seven days. After that, the tool deletes it the next time someone starts a build with images. Then the screen shows Deleted. Press Build with images to build it again.

The tool tells you if the archive still matches the installation. The build records the image versions it was made from. The screen names every service whose version has changed since then. An archive built before this record existed shows cannot be checked. That does not mean it is fine or out of date. It means the tool does not know. Build a new archive fetches all images again. After you press it, the old archive is no longer offered. For this reason it is not the main button on that screen.

A "ready" archive that is not there. Expect this failure after the tool itself restarts. The archives may be kept on storage that is lost on restart. Then the record still says ready, but the file is gone. The download says exactly this and names the cause. Build the archive again, and ask an administrator to fix the storage. See the environment variables.

Downloading the offline bundle counts as delivering the installation. You need write access to the installation. The archive carries that installation’s configuration.

An offline install also depends on two things that are easy to miss:

  • Some services are built on the target machine, not pulled. Their base images are in the archive too. An archive without them fails in the same way as one without an application image.

  • A successful load proves the archive was valid. It does not prove it held what this server needs. So after loading, the installer checks every image the manifest names.

Build the image archive by hand

This section explains the second way. You build the archive yourself, without Deployment Manager pulling the images. Every bundle includes a script for this: a shell script and a PowerShell version. It fills in the same images.tar.gz files.

  1. Use a laptop or jump host that has Docker and a route to the registry.

  2. Run the script there.

  3. Carry the finished archive to the site in the normal way.

Use this in two cases. The bundle was created before the images were needed. Or you want to pull the images from a place that Deployment Manager cannot reach.

What the installer asks

This section lists the installer’s questions. deploy.sh runs with no arguments. It asks a short, fixed set of questions. You can change every answer. Nothing is written until the questions are done.

Question What the answer means

Install all servers from here?

Asked first, and only when the machine you run it on reaches every other server over SSH without a password prompt — it checks each one and prints a line per server. Yes installs all of them from there: one tab per server, and servers that do not depend on each other install at the same time. ←/→ switch tabs; q closes them without stopping the install, and ./deploy.sh --attach reopens them. No installs this server only.

Where are you running this?

Asked when it did not offer to install all servers from here. On one of the target servers installs this server only. On your own machine installs every server over SSH.

Which of these servers is this machine?

Asked on a target server whose host name does not say which one it is. Pick it by its name and address.

Install directory [/usr/local/ft-system]

Where the install lives: the compose file, the configuration and the containers' data. Files are copied there, so the unpacked archive is only the delivery and can be deleted. Re-running with the same directory keeps the .env with this install’s secrets.

SSH user for the servers

Asked only after On your own machine: the account it logs in as on every server. One server needs another account? Put SSH_USER_<server-id>=<user> before ./deploy.sh, with the dashes of the id as underscores.

Can these servers reach the image registry (FT HUB)?

Yes pulls the images during the install. No loads them from the archive.

Wait for the containers to report healthy?

Yes waits until every container is healthy and names any that never gets there. No stops once they have started — faster, but it does not show the install works.

Dry run first?

Yes prints every command and changes nothing. Run again and answer No to install.

One password per secret

Enter generates a strong password — there are no defaults. One value is offered instead: the FT ACS web-service password the image ships with; keep it unless it was changed in ft-configs. At the end the script writes ft-credentials-<env>.txt with every password it set. Save the values and delete the file — most of them exist nowhere else.

After these questions, the installer asks for secrets separately, once per name. See how a secret’s answer is decided and the four reasons a password is refused.

Where an installation lives on the server

This section explains the install directory, and what happens if it is in use. You give the install directory as an answer. Everything goes there: compose.yml, the environment files, the mounted configuration, and all data the containers write. Before copying anything, the installer checks what is already in that directory:

What is found What happens

Nothing

A fresh install. The archive’s files are copied in and the install continues as normal.

This same installation, already there

Updated in place. The install continues. The environment file already on the server is kept. It holds this install’s existing secrets. It is not replaced with an empty one.

Another server of ours

Refused. Two servers cannot share one directory. You must choose a different path.

A compose file that this tool did not write

Refused. The installer does not overwrite an installation it does not recognize.

The installer checks only the server name, in the server-id file. It does not check which installation the directory belongs to. Two installations made from the same topology use the same server names. So use a separate directory for each installation.

The standard directory may be in use or not readable. Then the installer offers its own directory and tells you. A command written for the standard path will not find the install there. So write down which path was actually used.

Good to know

This section lists facts that help later.

  • Configuration files are protected once they exist on a server. Each configuration file in the bundle carries the checksum it was written with. A checksum is a short code calculated from the file’s content. With it, a later deploy can tell two cases apart. Either nobody touched the file, or a customer edited it by hand on the server. The deploy does not overwrite a file that was edited. See what a deploy does with that. That page also covers the one exception. A service’s own contract can set it for a specific file with config_policy: (keep or replace). An example is keeping a certificate a customer supplies.

If something goes wrong

This section says where to look when creating a bundle fails.