Upgrades And Restarts | BareBones Ticketing Manual

A restart applies a saved setting or brings the same version back up. An upgrade changes the installed version and may change the database. This page covers both, and says what going backwards does and does not require.

Before you start

For a restart: the folder, permission, certificate, proxy, or secret work that the new setting depends on is already finished.
For an upgrade: the new package, its manifest, and its checksum, all checked; a current backup of all four continuity classes; and the conditions in Change control.

Restart

Restart when the version is not changing and a saved setting takes effect at startup. The attachment storage path and the Data Protection key-ring path are two such settings.

On Windows:

Restart-Service -Name BareBonesTicketing

On Linux, from the package root:

docker compose restart

Where this installation points at an external PostgreSQL server, that command restarts the web container only. The bundled database container runs only in installations that use it, so there is nothing else for the command to restart.

Check it came back. On Linux:

docker compose ps

A restart does not move data. Saving a new attachment path does not copy existing attachments to it, and saving a new key-ring path does not move existing keys. Copy the content first, as a separate planned step, or the restart strands it.

Upgrade on Windows

The Windows path is: run the new package's installer. It is the same command as a first install.

Extract the complete new package to its own folder. Do not extract it over the old one and do not run it from inside the archive.
Check that the package, manifest, and checksum agree, and that they name the version you approved.
Back up all four continuity classes. See Backup and restore.
Run the new package's Install-BareBonesTicketing.cmd as Administrator.
Wait. The installer keeps the database mode, the generated runtime database identity, the configuration, the product-managed PostgreSQL data, the attachments, and the Data Protection keys. It stops the service, keeps a copy of the previous application files under C:\ProgramData\BareBonesTicketing\backups, applies the target version's database setup and migrations, reinstalls and starts the service, and tests the local https://localhost:8443/setup route.
Read the final result. Continue only if it reports success.

If it failed, read C:\ProgramData\BareBonesTicketing\install\last-install-failure.json for the stage that failed, then the Windows Event Viewer Application and System logs.

Run the checks below.

Upgrade on Linux

The Linux path is: replace the bundle files and the image, then rerun the database script.

Stop inbound traffic. Database setup must not run against live work.
Back up PostgreSQL, the attachments volume, the key-ring volume, .env, and the exact current bundle.
Load the new vendor image artifact and replace the delivered bundle control files with the new ones. Keep your existing .env.

configure-database.sh is one of those control files. Replacing it matters: the assistant you run in the next step must be the one that shipped with the version you are moving to, not the copy left from your last upgrade.

From the new package root, run:

bash ./configure-database.sh

For an installation that uses an external PostgreSQL server, run:

bash ./configure-database.sh --database-mode external

Wait. The script keeps the runtime database identity, stops web, applies pending migrations, reconciles privileges on the target, checks that the runtime identity can do what it needs and no more, updates protected configuration, and starts web.
If the script fails, do not start web yourself. Its failure is the check working, not a step to skip.
Run the checks below.

What normal startup will not do

On both families, ordinary application startup never applies migrations. Configured as Production — which every supported deployment is — it also refuses to start when the database has pending schema changes, when the runtime database identity lacks access it needs, when that identity has more authority than it should, or when it could reach audit history through an update, delete, or cascade path. Any other environment name skips those checks and records one startup log warning saying so — see PostgreSQL.

If startup refuses for one of those reasons, rerun the package's database assistant — the Windows installer or configure-database.sh. Do not grant the runtime identity more privileges to get past it.

Check it worked

The service or container is running and the application responds.
The running version matches the version you approved.
An administrator signs in.
An attachment stored before the change retrieves.
A protected setting still decrypts.
System Diagnostics shows no new unexplained failure. See Diagnostics and logs.
Whatever external check your change record named — the public address, the proxy, the certificate — succeeds.

Remove an installation

The package ships a supported uninstall for both platforms: deploy/windows/Uninstall-BareBonesTicketing.ps1 and deploy/linux/uninstall.sh. Use it for a clean reinstall or a decommission rather than deleting directories and services by hand.

Both are conservative by default. Left to themselves they stop and remove the service or the Compose project and leave your data alone. Everything destructive is a separate switch you have to ask for — on Linux --remove-data, --remove-images, --remove-package-files; on Windows -RemoveManagedPostgreSql and -RemoveProgramData.

Each destructive option also requires you to type the installation's name back to the script — --confirm BareBonesTicketing on Linux, -ConfirmInstanceName on Windows. That is there so a destructive uninstall cannot be run by recalling a command from history on the wrong machine. Treat being asked to type the name as the last point at which you check which server you are on.

Uninstalling is not a backup step and not a downgrade path. Take and verify a backup first — see Backup and restore — because a removal that takes the data with it has no undo.

Going backwards is a restore, not a downgrade

Replacing application files or container images is not a database rollback. Once a migration has run, the schema has changed, and older binaries running against the new schema is a broken installation, not a previous one.

Two things the packages keep are recovery aids, not rollbacks:

Windows keeps a copy of the previous application files under C:\ProgramData\BareBonesTicketing\backups.
Linux keeps .env.pre-database-setup after a successful first preflight.

To actually return to the previous state after a schema or data change, restore the complete prior set — PostgreSQL, attachments, Data Protection keys, configuration, and the matching package — from one recovery point. That procedure is Backup and restore. Decide which way you are going before you start the change, not after it fails.

If it does not work

The Windows installer fails partway. Read last-install-failure.json for the stage name, then the Event Viewer logs. When database setup did not complete, the installer may restart the previous service. Fix the cause and rerun the same package.

configure-database.sh fails on Linux. A preflight failure happens before web is stopped and before .env is replaced. A later failure keeps both the retry .env and .env.pre-database-setup, but does not restart the previous web. Read docker compose logs web, and docker compose logs db if this installation runs the bundled database container — with an external PostgreSQL server there is no db container and that command returns nothing. Do not start web by hand to see what happens.

Something is wrong after the change. Stop changing things. Compare the installed identity, the migration state, diagnostics, and logs against what the change record said to expect. Then take the recovery decision you agreed in advance. Do not loop restarts and do not apply an older package speculatively.