Operating the Appliance

The appliance keeps its files in /opt/broch, with its settings in /opt/broch/.env. Each template’s README has the full detail: Azure, AWS. Upgrading & Rollback covers what every platform shares.

Shell Access

SSH is closed by default.

Azure: run commands with az vm run-command invoke, or use the Serial Console. The Serial Console user is broch, and its password is the vm-admin-password secret in the break-glass Key Vault (breakGlassKeyVaultName output). Reading it needs the Key Vault Secrets User role on that vault. The password changes on every redeploy, so read it again after each one.
AWS: use SSM Session Manager: aws ssm start-session --target <instance-id>, also given as the SsmCommand output. It needs the Session Manager plugin on your machine. There’s no key pair to manage.

To watch certificate issuance after first boot:

# Azure
az vm run-command invoke -g broch-rg -n <vm-name> --command-id RunShellScript \
  --scripts 'cd /opt/broch && docker compose logs --tail 50 caddy'

# AWS, inside a Session Manager session
sudo docker compose -f /opt/broch/docker-compose.yml logs --tail 50 caddy

Upgrade

Back up first, and pin a release, not latest. Upgrading & Rollback covers why.

Azure. Change the version in .env and recreate the broch container. Caddy keeps serving across the restart.

az vm run-command invoke -g broch-rg -n <vm-name> --command-id RunShellScript --scripts '
  cd /opt/broch
  sed -i "s|^BROCH_VERSION=.*|BROCH_VERSION=<new-version>|" .env
  docker compose pull broch && docker compose up -d broch'

AWS. Update the stack’s BrochVersion parameter and nothing else: in the console, Update → Use existing template. The README’s Upgrading Broch has the command-line form. Within a few minutes the instance pulls the new image and recreates broch in place.

Don’t edit BROCH_VERSION in .env by hand. The instance resets it to the stack’s value on every start.
A downgrade isn’t applied. The stack update completes, but the instance keeps the newer version and says why in /opt/broch/version-mismatch. Set BrochVersion back to the running version, or the stack records a version older than your database.
No new version after five minutes? Read sudo journalctl -t broch-version over Session Manager.
A stack created from an earlier template version needs its instance rebuilt once first. See the README’s Upgrading Broch.

Change Settings and Secrets

The appliance writes /opt/broch/.env on its first boot only, from the deployment’s parameters and the secrets in Key Vault (Azure, keyVaultName output) or Secrets Manager (AWS). A later redeploy or stack update doesn’t rewrite it; on AWS, BrochVersion is the one exception. So changing a setting or a secret takes two steps:

Update the running instance: edit the line in /opt/broch/.env, keeping the value inside its single quotes, then recreate the containers with cd /opt/broch && docker compose up -d (with sudo on AWS). Compose reads .env only when it creates a container, so a plain restart keeps the old value.
Update the stored value, so a rebuilt instance gets it. On Azure, set a secret in Key Vault, after granting yourself access with az keyvault set-policy -n <keyVaultName> --upn <you> --secret-permissions get set (each redeploy resets the vault’s access policies), and pass the new value on your next redeploy. A redeploy can change only secrets while the VM exists: a changed setting fails with PropertyChangeNotAllowed, so keep it in your parameters for the next rebuild (see Recover). On AWS, set a secret in Secrets Manager, and pass the same value for its parameter on your next stack update; an update that changes a setting stops and starts the instance.

The Local database password can’t be changed this way on either cloud, because Postgres keeps its first password. Neither can the AWS NewServer one. The Azure Managed admin password changes only by redeploying with a new postgresAdminPassword; then update BROCH_DB_CONNECTION_STRING in .env. To renew your own certificate, replace its files on the instance and recreate Caddy; each README’s TLS section has the detail (Azure, AWS).

The master key wraps everything Broch encrypts at rest. Changing it is recoverable but not free: signed-in users sign in again and usage counters reset. See At-Rest Encryption.

Back Up

All state is in the database, so back up the database and your master key, not the VM. Take a backup before every upgrade.

Database	Backups
Azure `Managed`	Flexible Server automated backups and point-in-time restore
AWS `NewServer`	RDS automated backups, plus a final snapshot when the stack is deleted
Your own database	Your own backup process
`Local`	None automatic. Snapshot the data disk or volume on a schedule, or run `pg_dump`. The READMEs have the commands: Azure, AWS.

Recover

To rebuild a broken instance, redeploy your existing deployment rather than starting fresh, and come back at the version your database is on. A newer version migrates the database on boot, irreversibly.

Azure: Azure won’t change an existing VM’s boot configuration, so if the VM still exists, delete it first (az vm delete -g <rg> -n <vm-name> --yes). The data disk and Key Vaults are separate resources and survive; so does the OS disk, which you can delete once the new VM is up. Then, in the resource group, open Deployments, select the last successful deployment and choose Redeploy, re-entering the same master key, the localDbAdminPassword if you set one (left blank, it’s replaced by the derived default), and any certificate, Google Cloud DNS key or registry token you supplied, which aren’t kept in Key Vault. If you’ve upgraded in place since, change brochVersion to the version you’re running. Don’t recover through a fresh Marketplace form, which defaults to the latest release.
AWS: replace the instance by updating the stack with UbuntuAmi set to a newer Canonical release path, keeping BrochVersion at the version you’re running. Most other parameter changes keep the broken instance. Local mode, and a bring-your-own Elastic IP for a database outside the VPC, need a delete and re-create instead.

Each README’s Recovering an existing installation section has the steps: Azure, AWS.

Tear Down

Record your master key first if you might redeploy against the same data.

Azure. For a dedicated resource group with no Local database to keep, az group delete --name broch-rg --yes removes everything, including a Managed database. In Local mode that also deletes your database: snapshot or move the <vm-name>-data disk out of the group first, and read POSTGRES_PASSWORD from /opt/broch/.env (without its quotes): a resource group with another name or in another subscription derives a different one, so pass it as localDbAdminPassword when you redeploy. With a database or anything else you want to keep in the same group, delete only this deployment’s resources. The README’s Teardown has the commands, and covers redeploying while the Key Vaults are still soft-deleted (7 days).

AWS. aws cloudformation delete-stack --stack-name broch. RDS and the Local data volume take a final snapshot, which persists and bills until you delete it. Your own database is left untouched. To bring Local data into a new stack, you’ll need the same database password: if it was generated, read POSTGRES_PASSWORD from /opt/broch/.env before deleting. Restore by creating a new stack with DataVolumeSnapshotId, the same master key and BrochVersion, never by updating the existing one. The README’s Teardown has the restore steps.

Both. DNS records the appliance created automatically outlive teardown, except Route 53 records the AWS stack created. Delete them, so they don’t point at an address someone else may be given next.