feat: let an operator claim an instance and set its providers from the app

[suiramdev]

Summary

A new instance serves a /setup wizard. The first account claims it with a token the server prints to its log (or FREENARY_SETUP_TOKEN), becomes the OPERATOR, then picks the bank and email providers one screen at a time. Save and continue probes the credentials against the real service, then seals them (AES-256-GCM, key from BETTER_AUTH_SECRET) into a new instance_setting table; Finish setup restarts the server and the page reconnects. An environment variable always wins: a provider the environment configures in full shows as a read-only card, and environment values reach the browser masked. Read packages/instance-config (resolve.ts, seal.ts, claim.ts), then packages/api/src/routers/instance.ts.

Motivation

• Self-hosting required editing .env and restarting for every provider change, with no feedback until the first failed sync or email.
• A fresh deployment opened on an empty home screen with no hint that providers were unset.
• Probing on save catches wrong credentials, including ones in .env, when they are typed.

Drawbacks

• A database dump now carries credentials; rotating BETTER_AUTH_SECRET makes stored values unreadable until retyped.
• Finish setup restarts by exiting the process, so it needs a supervisor (restart: unless-stopped); under bun run dev the server stays down.
• Save anyway can store an untested credential (a warning toast says so).
• A new package (@freenary/instance-config) and a UserRole column on user.

Prior art

• First-run claim wizards (Jellyfin, Home Assistant); the log-printed token is added because the origin may be public.
• Gitea's install page writes settings the environment can still override; same precedence here.
• Rejected: a second entry point of @freenary/env — resolving stored settings needs Prisma (see docs/engineering/platform.md).

Notes

• Migration: 20260922120000_instance_configuration (adds UserRole, user.role, instance_setting).
• New optional env var FREENARY_SETUP_TOKEN; a signed-in user on an unfinished instance is sent to /setup.
• Visual change: new /setup wizard (claim, provider tiles, credentials, environment card, review); the shared wizard stepper gains a readable current step and a new check animation, which /onboarding also shows.
• Tests: packages/instance-config/src/seal.test.ts, packages/api/src/instance/{merge,mask}.test.ts.
• Docs: new self-hosting/setup.mdx and a troubleshooting entry; updated quickstart, self-hosting/{index,configuration,email,bank-providers,security,backup-and-restore}, contributing/data-model.
• Review gate: the reviewer agent approved the setup-link and redirect changes; it has not yet run over the later setup-flow commits.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 776bce7e-d14b-4a9b-93f1-78517c65072f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}