@towerism/selfhost-kit

selfhost-kit

Shared platform code for Towerism's self-hosted Nuxt 4 apps: play-pokemon-attendance-web and Tournament Genie.

It holds the security-sensitive infrastructure both apps need, so that there is one copy of it and a fix reaches both apps:

• an AES-256-GCM vault for secrets stored in SQLite;
• secret bootstrap (env first, else a file generated once under /data/secrets/) and the production launcher;
• a pino logger with redaction, and request ids;
• security headers and CSP, a rate limiter that knows about trusted proxies, and JSON-only and body-size guards;
• one-time setup codes;
• the container entrypoint (PUID/PGID, gosu, optional Litestream);
• reusable image and release workflows.

It ships as one npm package, @towerism/selfhost-kit, with a framework-free core and h3/Nitro adapters on @towerism/selfhost-kit/nitro.

Status: 1.0, stable. Both apps run on the kit (K4, K5), and the API they migrated onto is frozen: from 1.0 a breaking change is a major release (ADR-0005). api/ lists every export and the reusable workflows' interface, and CI keeps it in step with the build. docs/adopting.md walks an app through adopting it, and through the upgrade from 0.4.x.

Install

pnpm add --save-exact @towerism/selfhost-kit

Requires Node 24.11 or later. The package is ESM only. What each entry point needs in the app:

• @towerism/selfhost-kit: nothing more.
• @towerism/selfhost-kit/nitro: h3 (Nitro brings it; it is the kit's only peer dependency, optional).
• @towerism/selfhost-kit/testing: vitest and h3 in the app's devDependencies. The kit's CI tests it with the Vitest major in the kit's own lockfile.
• @towerism/selfhost-kit/release-config: semantic-release, @semantic-release/exec and conventional-changelog-conventionalcommits in the app's devDependencies.

/testing and /release-config find those tools in the app's own node_modules. pnpm's default isolated layout, npm and Yarn with node_modules all work. pnpm's global virtual store (enable-global-virtual-store) and Yarn PnP are unsupported for those two entry points.

Pin an exact version and let Renovate propose each bump; majors are never automerged. See docs/adopting.md.

Security

To report a vulnerability, see SECURITY.md. Don't open a public issue.

Read first

• Architecture: context, goals, the package layout, API sketches, the /data contract, how fixes reach both apps, the migration plan, risks and milestones.
• Architecture Decision Records
• Follow-up issues for the apps (drafts)
• Adopting the kit: wiring each piece into an app, and upgrading from 0.4.x
• API report: every export and the reusable workflows' interface, generated by pnpm api:report
• Ops assets: the Dockerfile lines, the caller workflow, the release config and the Renovate group an app needs
• Releasing: how versions are published, the credentials involved (none stored), rollback, and what to do when a release fails

Development

pnpm install --frozen-lockfile
pnpm lint && pnpm typecheck && pnpm test   # test includes the coverage gate
pnpm build && pnpm api:check && pnpm check:package && pnpm test:package
pnpm api:report                            # after an API change: regenerate api/ and commit it
pnpm test:entrypoint                       # Docker: builds the fixture image and runs the container tests
pnpm bench                                 # logger throughput, by hand; report it in PRs that touch logging

Commits follow Conventional Commits: they decide the next version.

Scope

This package serves the two apps above. It is public, but its API follows their needs, and semver promises cover only the documented API. It contains no secrets or deployment-specific values. Every key, token or address in its tests is synthetic.

License

MIT