Install On Linux With Docker Compose

This page installs the vendor-supplied Compose bundle on one Linux host.

The bundle defines three services. Only web runs all the time.

Service	What it is	When it runs
`web`	The application and its internal worker	Always
`db`	The bundled PostgreSQL 18 container	Bundled database mode only. It is behind the `bundled` Compose profile, so in external mode it is not created at all.
`authority`	A one-shot maintenance container that applies migrations and database privileges	Only when the database assistant runs it, behind the `maintenance` profile. It exits when it finishes.

Before you start

RHEL 9, Rocky Linux 9, Ubuntu Server 24.04, or Debian 12, under your organization's control.
Docker Engine and the Docker Compose plugin, installed through your normal host-management process.
The customer bundle, its manifest, integrity evidence, and legal material.
Durable storage for PostgreSQL data, attachments, Data Protection keys, and the deployment configuration. See Requirements.
Inbound TCP 8443 allowed by the host firewall. The product does not configure the firewall.
A decision on database mode. Bundled is the default. See PostgreSQL.
A decision about who is in the host's docker group — see below, and make it before you install rather than after.

The `docker` group is an administrator boundary

Treat membership of the host's docker group as administrator access to this installation. Anyone in it can read the Compose configuration, the container environment, the logs, the mounted volumes, and runtime secrets including the database credentials, using nothing but ordinary Docker commands. No product setting narrows that.

Put only trusted deployment administrators in that group. If your organization will not accept a trust boundary that wide, do not add people to the group at all — run Docker through a bounded sudo or root path instead. If you later find the membership was broader than you intended, treat the deployment secrets as exposed and rotate them.

The package's short-lived maintenance profile limits when the setup credential is in play, which is worth having, but it does not make docker group access a secret-isolated boundary. It is not one.

Install

Check that the bundle, manifest, integrity evidence, legal material, and version procedure all name the same product, version, and image. If they disagree, stop and return the bundle to whoever supplied it.
Extract the bundle into a directory you own. The package runbook uses /opt/barebonesticketing as its example. Apply your own ownership and permission policy before continuing.
Load the image carried by the bundle:
```
docker load -i images/barebonesticketing-web-<version>.tar
```
Replace <version> with the filename in your bundle. Do not pull an image from a registry.
Run the database assistant.

For the bundled database:
```
./configure-database.sh
```
For an existing PostgreSQL target:
```
./configure-database.sh --database-mode external
```
Answer the prompts. Each has a sensible default in [brackets] that you accept by pressing Enter — except the public application base URL, which has no default and is required; the assistant re-asks until you supply one. Both modes prompt, in order, for the database mode, the web image tag, the HTTP port, the HTTPS port, the public application base URL for email links, the database name, and the PostgreSQL setup username. External mode additionally asks for the PostgreSQL server, port, and SSL mode, and for the setup password (that prompt is hidden). In bundled mode the setup credential is generated and preserved internally, so there is no setup-password prompt.

The public application base URL is the address a recipient's browser will open from a link in an email the product sends, so give the address they can actually reach:
```
https://tickets.example.com:8443
```
Include the scheme, and include the port unless something in front of the application is already serving it on the standard one. A query string or fragment is discarded, and a trailing slash is added for you, so neither is worth typing.

A loopback or wildcard address is refused — localhost, 127.0.0.1, ::1, 0.0.0.0, *. Those work from the server itself and are useless in an email to anyone else, which is the whole reason the value exists. If you set one, System Diagnostics shows it followed by (rejected) and links fall back to whatever the request supplies.

In external mode the target database must already exist, and the setup login needs CREATEROLE or PostgreSQL superuser rights.
Wait. The assistant runs read-only preflight checks first. Only after those pass does it stop web, create or preserve the restricted runtime identity, apply migrations and privileges through a throwaway setup container, test the runtime connection, write .env with mode 0600, and start web.

Do not use --skip-connection-test. It is not proof of a working install.
Confirm what should be running is running:
```
docker compose ps
```
In bundled database mode you see web and db. In external mode you see web only — db is not part of that deployment. authority does not appear in either case; it has already run and exited. An empty or single-row result in external mode is not a failure.
Open https://<host-or-ip>:8443/setup. Your browser warns that the certificate is not trusted. That is expected on first start: the application is using its own self-signed bootstrap certificate.
Go to First administrator. Return here afterwards for step 10.
After you have saved approved hosts, storage paths, and the final certificate choice in Admin Settings, restart so those settings take effect:
```
docker compose restart
```

About `.env`

The assistant writes .env with mode 0600. Include it in your backup set — without it the deployment cannot be rebuilt.

Bundled mode keeps its generated setup password in .env, because the db service needs it. Only the runtime connection details reach web.

External mode removes the setup password from the final .env. Supply it again for a later setup or upgrade.

Check it worked

The host distribution and container tooling match the bundle procedure.
The bundle, manifest, and loaded image identities agree.
docker compose ps shows web running, and db running as well if you chose bundled mode.
The assistant reported successful preflight, migrations, and runtime connection verification.
https://<host-or-ip>:8443/setup responds.
Your installation record contains no password, connection string, certificate password, private address, or .env contents.
curl -fsS http://127.0.0.1:8080/health/ready returns {"status":"Healthy"} from inside the container. This is the same check Compose itself uses as the web healthcheck, so a container that never reaches healthy is telling you the application cannot reach its database.

See Diagnostics and logs for what the health routes do and do not prove.

If it does not work

The image will not load, or Compose will not start. Do not pull a substitute image, change the image identity, or recreate the storage volumes. Keep the error output and go back to the bundle owner.

Preflight fails. Nothing has changed yet. The previous web service and configuration are untouched. Correct the reported cause and rerun.

A step after preflight fails. The assistant keeps the retry configuration in .env and a one-time backup at .env.pre-database-setup. It does not promise to restart the previous web service. Do not start web by hand — rerun the assistant.

You need to upgrade. Back up PostgreSQL, attachments, the key ring, .env, and the current bundle. Load the new image. Replace the bundle control files with the new ones. Rerun configure-database.sh in the same database mode.

You need to restore. Recover the bundle, .env, PostgreSQL data, attachments, and key ring, then rerun the assistant in the restored mode. Then check that you can sign in, open an existing attachment, and read protected settings.

Setup is only reachable over an untrusted connection. Stop. Do not type administrator credentials. Go back to whoever owns HTTPS for this deployment.

Next step

First administrator.