Step 5. Test the bundle

This page shows you how to test a bundle before you install it for a real customer. Test install creates temporary test servers. It runs the same installer on them that a real site uses. Then the tool removes the servers.

A wrong value found here costs you one more test run. The same wrong value found at the customer’s site costs a failed site visit. So test the bundle before a first delivery.

Before you start

This section lists what must be ready before you can start a Test install.

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

Steps

This section shows how to run one Test install.

  1. Open the Installations tab.

  2. Find the card of your installation. Press Test install. The Test install screen opens.

  3. Press Start test install. The tool creates the temporary servers. A checklist shows each step.

  4. When the servers are ready, press Send the bundle to the servers.

  5. The installer deploy.sh starts in the terminal on the screen. deploy.sh asks for every secret here, exactly as on the customer’s server. Type the answers.

  6. Wait until the install finishes. The screen shows a pass or a fail.

  7. Optional: press Run checks to check the installed services again.

  8. When you are done, press Delete test servers. This frees your slot for other people.

If the install fails, the screen offers Run install again, Open shell to look, Explain this failure and Start a fresh test install.

Right after you create an installation, a dialog offers Run a test install. It opens the same screen.

What it checks, and what it never touches

This section explains what a Test install checks and what it never changes.

A Test install runs the installer of the bundle in bootstrap mode. It runs it only on servers this tool creates for the run. It is the same script that a real site sees. It asks the same questions in the same order.

What it proves: the bundle, the configuration in it, and the install script. It proves that the compose files, the configuration trees and the images pull, start and pass their health checks together.

What it does not prove: the customer’s network, their storage, their firewall, or their hardware. None of those exists on the test servers. A green Test install answers "will this bundle install". It never answers "will it work at that site". For this reason, the readiness checks still run against the real servers on the deploy that follows. They can still refuse.

Run it before a first delivery. It never fixes an installation that is already live and broken. The test servers have none of the state that makes that installation fail. For that case, see Step 7. Check that it works.

It never touches:

  • The installation’s own bound servers. The test servers are created new for the run. They belong to no customer. The servers you will really deploy to are never involved.

  • A customer’s site. There is no SSH connection to anywhere except the temporary servers.

  • The installation record itself. A run, pass or fail, changes nothing about the installation. Never delete or recreate an installation because a Test install failed.

You type every secret fresh on the test servers. None of it is carried forward. Later you deliver the bundle for real, by download or by deploy over SSH. Then every secret is asked again on the real server. A value typed into a test run never reaches a customer’s machine.

What you see: how it differs from a real install

This section lists the ways a Test install is different from a real deploy.

  • Delivery mode, not SSH deploy. A Test install runs the installer in the "carried to site" mode. This is the mode you use when you download a bundle and install it by hand. It is not the SSH-deploy mode used on a real customer’s servers.

  • Real servers, not a script dry run. The test servers are real, running containers. This is not a --dry-run. The images really pull and the services really start.

  • Two different limits, and only one of them is shared. An installation can have one active Test install at a time. A second start on the same installation is refused as a conflict. It is not queued. Separately, the test servers come from a small pool. Every installation and every operator share this pool. A refused start most often means the pool is full, not that something is wrong. The pool size is the number the test server service reports. If the tool cannot ask it, the size shows as not known, never as 0 of 5.

  • No consent step for reading its own evidence. On a real deploy, the tool asks you before it opens SSH to collect evidence from a customer’s server. The test servers were made by this tool minutes earlier, for this run only. Their failure evidence (the terminal transcript, secrets masked) is already in the browser. There is nothing more to fetch.

Good to know: what it costs and how long it lives

This section explains how many resources a run uses and how long it stays.

A Test install uses one of the five shared slots while the run is active. The occupancy list in the Installations header shows how many of the five are in use, and by which installation. Look there first if a start is refused. It tells you if the pool is full.

A run stays alive when you close the tab and open it later. You can also reach it by a direct link. Leaving the screen does not stop the run or the install inside it.

The test server service decides how long the servers of a finished run are kept. There are two cases:

  • It states the number of hours after which servers are deleted automatically.

  • Nothing deletes them. It says so plainly. A run then holds its slot until someone deletes it by hand.

The panel always says which case is true for its pool.

The last finished Test install for a bundle is shown in three places:

  • next to the installation,

  • on the first step of the Deploy flow,

  • on the checklist of the Download flow.

It shows pass or fail, and how long ago. A bundle can change after a Test install ran on an earlier version of it. Then a pass is shown as stale, not as a current pass.

What it needs to be available at all

This section lists what an administrator must configure before Test install works.

Test install is a separate feature. A second service creates the temporary servers. Three things must be configured on the Deployment Manager side, or nothing can be started:

  • The connection to that service: its address and a shared secret. If either one is missing, nothing can be started. The screen says test installs are not set up here. It does not report a failed request.

  • The key Deployment Manager uses to encrypt the temporary SSH keypair it creates for each run. If this key is missing, the same request fails for a different reason. The message names that reason.

Test install needs a bundle to install on the test servers. So Test install is greyed out on a card that has no servers bound yet. Its message is separate from the message for Deploy, which is greyed out for the same reason.

If something goes wrong: the four reasons it refuses to start

This section lists the four ways a start can fail and what to do for each.

A failure here is about the test servers, never about a real installation. None of the four means an installation is broken. None of them means anything was sent anywhere.

What happened What to do

The temporary servers were being created and the run stopped part-way.

Read the checklist step that tracks the server creation. It names which step stopped and what is still there. Use it to decide: start again from scratch, or retry only the part that failed. Do not delete the installation because of this.

The service that creates test servers refused the request before creating anything. The usual reason is that every slot is already taken.

Open the occupancy list (in the Installations header) to see who holds the slots. Start again when one is free. Nothing of yours was touched. No bundle was sent anywhere.

The connection that carried the start closed before a result arrived. The temporary servers may be up, or may not be.

Open the installation’s Test install screen again. It asks for the occupancy list again and shows what is really running. Do not start a second run first. A lost run holds a slot that nobody can find.

A request to delete the test servers did not succeed.

Check the occupancy list. If the run is still listed, ask the person who runs the test server service to clear it. The slot can look free here while the servers are still running.

For every message the tool can show, see When something goes wrong.