Muse Front Door — docs
Contents

White-label install guide

This guide takes you from a fresh clone to a running independent instance: your own domain, brand, VM, trust root, and clients. Nothing is shared with any other instance at runtime.

Time estimate: 1–2 hours if DNS and the VM are ready; most of it is waiting on DNS propagation and Let's Encrypt.

What you're building #

One self-hosted instance of the front-door system:

secrets — generated fresh, never copied from another instance. - Your clients, onboarded under your own ethics charter and consent records.

Prerequisites #

user. 2 vCPU / 4 GB RAM is plenty. - A local machine (Linux/macOS) with git, ssh, curl, and python3 (+ Pillow, for regenerating the social cards). - An SSH keypair for VM admin access.

1. Get the kit #

Clone the repo (or download the dist tarball anonymously):


git clone <kit-url> frontdoor

cd frontdoor

2. Run the wizard #


bin/white-label-init.sh

It prompts for the domain, brand names, package name, VM host/user, and terminal subdomain; writes config/white-label.yaml; re-renders the whole tree (Caddyfile, nav, themes, social cards, docs links); and prints a bootstrap checklist. Review the diff, then commit.

Re-render any time after editing the config:


bin/white-label-apply.sh

3. DNS #

Point at the VM's IP:

Proxying (e.g. Cloudflare orange-cloud) is optional. Wait for propagation before step 5 — Let's Encrypt needs to reach the VM.

4. Provision the VM #

On the fresh VM, as root, from this repo:


sudo ./vm/bootstrap.sh --admin-user <your-admin-user>

This installs Caddy, creates /srv/{apex,board,chat,dist,docs,ops,start, status,verify}, installs the board systemd unit, and hardens sshd for the reverse-tunnel workload. Idempotent — safe to re-run. See docs/VM-REBUILD.md for what bootstrap does and doesn't do.

5. Deploy the Caddyfile #

The wizard rendered vm/Caddyfile from vm/Caddyfile.tmpl for your domain. Copy it to the VM and reload:


scp vm/Caddyfile <user>@<vm>:/etc/caddy/Caddyfile

ssh <user>@<vm> sudo systemctl reload caddy

Certificates are issued automatically on first request.

6. Publish the tree #

From your local machine (needs SSH to the VM as the admin user):


bin/publish.sh

This ships the repo (committed files only — uncommitted work, including stray secrets, can never leak), deploys every site to /srv/*, and writes /srv/board/instance.json so the board server knows its own identity. Verify: https://example.com/ should show your branded landing page.

7. Create the trust root (fresh secrets) #

SSH to the VM and create, new — never copied from another instance:

SecretLocationHow
Operator PINserver-side verify flowSet it in the verify panel (https://verify.example.com/); the PIN secret lands in /srv/verify/.ops-secret (0600)
Age backup keypairyour local machineage-keygen; install the public key at /home/<user>/.config/frontdoor/backup-recipient on the VM. The private key never leaves your machine.
Fleet SSH keypairVMGenerated on first provision-remote.sh run; the private key lives at /home/<user>/.ssh/fleet (0600) and never leaves the VM.

Then read docs/SECRETS.md — it inventories every secret, its mode, and its rotation procedure. Run its audit checklist quarterly.

8. Provision your first machine #


bin/provision-remote.sh <name>

This registers the machine in gcp/machine-registry/PORTS.md (unique SSH + terminal ports), generates its keys on the target, sets up the reverse tunnel, health reporting, and the update channel. See docs/INSTALL.md for the full provisioning protocol.

9. Verify #

identity, services, and (once consented) agents. - https://status.example.com/ — health should go green as machines report in. - https://docs.example.com/ — your branded docs. - bin/health-report.sh on a provisioned machine; check the status page.

10. Before onboarding clients #

Two documents are load-bearing for operating ethically:

  1. docs/CHARTER-TEMPLATE.md — adapt the ethics charter to your

business, sign it (write the decision down, dated), and keep it where your agents can read it. 2. docs/CONSENT.md — no agent or client work appears in the public manifest without that client's explicit consent. Set up your consent records before the first client goes public.

Ongoing operations #

default (https://dist.example.com/<package>.tar.gz). Publish a new release with bin/publish.sh; machines pull on their poll schedule. Set REPO_TARBALL_URL on a machine to track upstream instead. - Backups. vm/backup.sh encrypts /srv to your age public key nightly. Test-decrypt yearly — an untested backup is a rumor. - New machines. `gcp/machine-registry/add-machine.sh <name>

<ssh-port> <terminal-port> on the VM; check PORTS.md` first.

/srv/board/allowed_signers. Full procedures in docs/SECRETS.md.

What not to do #

fresh credentials. The one deliberate exception is documented in docs/SECRETS.md (there isn't one — that's the point). - Don't sell under the "Muse" name. The product name is a config value; commercial instances need their own brand. - Don't put unconsented agents/work in the public manifest. See docs/CONSENT.md. - Don't skip the charter. docs/CHARTER-TEMPLATE.md exists so the ethical call is made once, in writing, before the first client — not improvised per task.