Masterplan Optimiser
General audience

Operator Guide

Installation & First Deployment

Provision a fresh Ubuntu VPS, let the guarded wizard generate protected configuration, and register the first root passkey without placing secrets in Git or .env.

Before connecting

  • Use a fresh Ubuntu 22.04 or 24.04 VPS with a public IPv4/IPv6 address.
  • Create the application DNS record before passkey registration. The hostname becomes the WebAuthn relying-party identity.
  • Install an SSH public key and verify the host fingerprint through the provider panel.
  • Decide whether this is standalone or one node of a future two-node HA pair.

1. Provision the host

VPS SSH

Connect as root, clone the trusted repository, and run the provisioning script:

ssh root@VPS_ADDRESS
git clone REPOSITORY_URL /opt/masterplan
cd /opt/masterplan
sudo ./deploy/setup-server.sh

The script installs Docker, age, jq, dialog, rsync and SSH tooling; configures UFW/fail2ban; creates or preserves the deploy account; and grants Docker access. Reconnect afterwards so the new group membership applies.

2. Run guarded configuration

VPS SSH

ssh deploy@VPS_ADDRESS
cd /opt/masterplan
./configure-production.sh

The command opens the same full-screen interface as mp-opt. The wizard collects the domain, passkey display name, database password choice, VAPID contact and optional SMTP settings.

It writes non-secret configuration to mode-0600 .env and creates protected Docker secret files for the application secret, VAPID private key, root bootstrap token and optional SMTP token. The SMTP token is never stored in .env.

3. Deploy and verify

MP-OPT

Select Deploy and services → Build and deploy the current checkout. Wait for the backend health check, database migrations, Caddy validation and public HTTPS health check to pass.

Browser

Open https://YOUR_DOMAIN/health. Accept only HTTP 200 with database health true. Then open the root bootstrap page.

4. Register the root passkey

VPS SSH

Read the bootstrap token only in the trusted SSH terminal:

cd /opt/masterplan
cat secrets/root_bootstrap_token

Browser

Enter only the token value on the bootstrap page and register a discoverable passkey. The shell prompt, hostname and command are not part of the token.

MP-OPT

After root login succeeds, select Root administrator recovery → Disable bootstrap after registering a root passkey.

5. Establish recovery before real data

  1. Generate the operator-held age recovery identity on a trusted workstation.
  2. Keep two protected copies and configure only its public age1... recipient.
  3. Create a complete recovery snapshot and deep-verify it with the private identity.
  4. Export the resulting .mpopt-snapshot to the workstation and confirm its SHA-256.

Follow Recovery Encryption Keys and Recovery Snapshots.