atrium bootstrap
- Repo stars 0
- Author repo skills-registry
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Moderate
- Setup complexity
- Manual integration
- External API key
- Required · Vendor-specific
- Operating systems
- Linux · Docker
- Runtime requirements
- Node.js · Python · Docker
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 8. .env.example
Copy from [`README.md`](README.md) section *Step 7* and fill secrets with placeholders. Tell the user to generate `APP_SECRET_KEY` and `JWT_SECRET` with `openssl rand -hex 48`. Don't commit `.env` — only `.env.example`.
# Bootstrap a new project on top of atrium
Atrium ships as a Docker image (`ghcr.io/<org>/atrium:<X.Y>`). The host
project lives in its own repo, `FROM`s the atrium image, adds a backend
Python package + a frontend host bundle, and wires both in through a
narrow contract. **Never edit atrium files** — the next upgrade replaces
them.
The companion guide [`README.md`](README.md) in this directory is the
verbose reference (full file templates, retrofit playbook, gotchas). The
canonical worked example is [`../../examples/hello-world/`](../../examples/hello-world/).
This SKILL.md is the procedure to follow when an agent is doing the
bootstrap.
## Default to the scaffolder
For a vanilla host (single Python module, single frontend bundle, the
standard extension shape), **run the scaffolder rather than emitting
files by hand**:
```sh
npx @brendanbank/create-atrium-host <project-name> --yes-defaults --no-git
```
The emitted repo wires every registry slot, ships CI, and uses the
published `@brendanbank/atrium-host-*` packages — its `frontend/src/main.tsx`
is the post-foundation shape (~10 lines, no wrapper-element code). Skim
the emitted README and the demo `Welcome*` components, delete what
you don't need, and start adding your domain code.
Drop down to the manual procedure below only when the user explicitly
asks for a non-default shape (multiple host packages in one repo,
custom alembic layout, ship-your-own-SPA, retrofit of an existing
codebase).
> **Example version-pinning.** `examples/hello-world/` tracks `master`
> and exercises whatever extension surface ships at HEAD. If the user
> pins their atrium image to an older `X.Y` tag (sensible for prod),
> read the example **at the matching git tag** — `git checkout vX.Y.Z
> -- examples/hello-world/` — before copying snippets. The host
> registry tolerates calls to slots that don't exist in the running
> image (logs a console warning, the rest of the bundle continues
> registering), so a newer-than-image bundle degrades gracefully
> rather than catastrophically — but the slot still won't render.
## Up-front decisions to confirm with the user
Before writing files, confirm:
1. **Project / image name** (e.g. `bookings`). Used as the docker image
tag and project root.
2. **Python module name** (e.g. `bookings`). Importable on PYTHONPATH;
referenced by `ATRIUM_HOST_MODULE=<module>.bootstrap`. Must not
collide with `app` (atrium owns it) or any pip-installed package.
3. **Atrium image pin**: `ghcr.io/<org>/atrium:<X.Y>` for patch uptake,
`:<X.Y.Z>` for fully deterministic deploys. `:latest` is for tinker
only — refuse it for any branch the user calls "prod".
4. **Public hostname + URL** for `APP_BASE_URL`, `WEBAUTHN_RP_ID`,
`WEBAUTHN_ORIGIN`. Localhost is fine for local dev.
5. **Whether they're retrofitting an existing app**. If yes, ask which
concerns atrium can take over (auth, audit, email, jobs, admin shell)
so existing code can be deleted rather than ported.
Don't assume answers. Mismatched module names or the wrong image tag
fail late and noisily.
## Procedure
Below, `<your-app>` is the project name and `<your_pkg>` is the Python
module name. Replace both consistently.
### 1. Repo skeleton
```bash
mkdir -p <your-app>/{backend/src/<your_pkg>,backend/alembic/versions,frontend/src}
cd <your-app>
git init
```
Add a top-level `.gitignore` covering `.env`, `node_modules`, `dist/`,
`__pycache__/`, `.venv/`, `*.pyc`.
### 2. Backend host package
Create these files (full contents in [`README.md`](README.md), section
*Step 2*):
- `backend/pyproject.toml` — hatchling, name `<your-app>-host`, no
runtime deps (atrium image provides them).
- `backend/src/<your_pkg>/__init__.py` — empty marker.
- `backend/src/<your_pkg>/bootstrap.py` — define `init_app(app:
FastAPI) -> None` and optionally `init_worker(host: HostWorkerCtx)
-> None` (`from app.host_sdk.worker import HostWorkerCtx`).
`init_app` mounts your router. `init_worker` registers job
handlers via `host.register_job_handler(kind=..., handler=...,
description=...)` and APScheduler ticks via
`host.scheduler.add_job(...)`. Either may be absent (atrium logs
`host.init_app.absent`); both run loud if the module fails to import.
**Call `register_namespace(...)` at module top-level**, not inside
`init_app` — atrium imports `bootstrap.py` from both the api and the
worker process, but only the api calls `init_app`. A namespace
registered inside `init_app` is invisible to worker handlers and
every `get_namespace(session, "ns")` from there will `KeyError`.
- `backend/src/<your_pkg>/models.py` — define `class HostBase(DeclarativeBase)`
and your tables on it. **Never** parent host tables on `app.db.Base`.
- `backend/src/<your_pkg>/router.py` — a normal FastAPI APIRouter.
Use `prefix="/api/<your_pkg>"` so the SPA owns un-prefixed URL
space (atrium issue #89). Imports atrium's `current_user` (auth
required) or `require_perm("...")` (permission required) for
gating.
### 3. Alembic chain
- `backend/alembic.ini` — uses `%(here)s` so `script_location` resolves
to the file's directory, not the caller's CWD.
- `backend/alembic/env.py` — copy from atrium's `backend/alembic/env.py`
and adjust:
- `target_metadata = HostBase.metadata` (host tables only)
- `version_table = "alembic_version_app"` (separate from atrium's
`alembic_version`)
- Add `process_revision_directives=emit_host_foreign_keys` (from
`app.host_sdk.alembic`) so cross-base FKs declared with
`HostForeignKey` land in autogenerated migrations.
- Add an `include_object` filter so autogenerate doesn't propose
`drop_table` ops for atrium's tables. See `../host-models.md` for
the boilerplate.
- `backend/alembic/versions/0001_init.py` — `op.create_table(...)` your
domain tables, then `seed_permissions_sync(op.get_bind(), [codes],
grants={"role": [codes]})` for permissions. `super_admin` is
auto-granted; unknown role codes warn and skip.
### 4. Frontend host bundle
The bundle is a separate Vite project that emits one ES module
(`main.js`) atrium dynamic-imports on SPA boot. Ship its own React,
ReactDOM, Mantine, TanStack Query — atrium's React stays out of the
host subtree.
- `frontend/package.json` — react/react-dom 19, mantine 9, tanstack
query 5, vite 8, typescript 6, tabler icons 3. Single script: `vite
build`. **Add `vite-plugin-css-injected-by-js` as a devDependency** —
see vite.config.ts below.
- `frontend/vite.config.ts` — library mode (`build.lib`), single
output `main.js`, define `process.env.NODE_ENV` and `process.env`
so React/TanStack don't throw on a missing process shim. **Plug
`vite-plugin-css-injected-by-js` into `plugins`**: Vite's lib build
extracts every `import 'pkg/styles.css'` into a sibling
`<bundle-name>.css`, but atrium dynamic-imports `main.js` only —
the sibling never loads and the page renders unstyled. The plugin
rewrites those imports to inject CSS via a runtime `<style>` tag,
so a single `main.js` carries everything. Add it preemptively even
if the bundle has no CSS imports today: the failure mode (silently
unstyled widgets) is annoying to diagnose later.
- `frontend/src/main.tsx` — the entry. Reads `window.React` and
`window.__ATRIUM_REGISTRY__` (both set by atrium's main.tsx before
the dynamic import). Calls `reg.register{HomeWidget,Route,NavItem,AdminTab,ProfileItem}`.
- `frontend/src/api.ts` — plain fetch with `credentials: 'include'` so
the atrium auth cookie is sent. Default base URL `/api`.
- `frontend/src/queryClient.ts` — a single `new QueryClient(...)`
shared across every component the bundle registers.
- One `<Component>.tsx` per slot — each wraps its tree in
`<MantineProvider>` + `<QueryClientProvider client={queryClient}>`.
### 5. Two-React-trees pattern
The wrapper is mandatory:
```tsx
const AtriumReact = (window as unknown as { React?: { createElement: (...a: unknown[]) => unknown } }).React;
type MountedEl = HTMLElement & { __hostRoot?: Root };
function mountInside(el: HTMLElement | null, child: React.ReactElement): void {
if (!el) return;
const slot = el as MountedEl;
if (slot.__hostRoot) return;
slot.__hostRoot = createRoot(slot);
slot.__hostRoot.render(child);
}
function makeWrapperElement(child: React.ReactElement): unknown {
return AtriumReact!.createElement('div', {
ref: (el: HTMLElement | null) => mountInside(el, child),
});
}
reg.registerHomeWidget({
key: 'your-widget',
render: () => makeWrapperElement(<YourWidget />),
});
```
Atrium's React creates the wrapper `<div>`; the bundle's `createRoot`
mounts inside it via the ref callback. Two reconcilers, no shared
hooks. The `__hostRoot` guard makes the ref idempotent under
StrictMode / route remounts.
Hooks-free elements (Tabler icons, plain SVG) can be passed directly to
atrium's React via `AtriumReact.createElement(IconHome, { size: 18 })`
— used for nav-item and admin-tab icons.
### 6. Dockerfile
Two-stage build: node-builder for the SPA, then `FROM ${ATRIUM_IMAGE}`
to install the host package and copy the bundle into the static dir:
```dockerfile
ARG ATRIUM_IMAGE=ghcr.io/<org>/atrium:0.26
FROM node:25-alpine AS frontend-builder
WORKDIR /app
RUN npm install -g pnpm@10.33.1
COPY frontend/package.json frontend/pnpm-lock.yaml* ./
RUN pnpm install --frozen-lockfile 2>/dev/null || pnpm install
COPY frontend/ ./
ARG VITE_API_BASE_URL="/api"
ENV VITE_API_BASE_URL=${VITE_API_BASE_URL}
RUN pnpm build
FROM ${ATRIUM_IMAGE} AS runtime
USER root
COPY backend /opt/host_app
RUN /opt/venv/bin/python -m ensurepip --upgrade \
&& /opt/venv/bin/python -m pip install --no-cache-dir /opt/host_app
COPY --from=frontend-builder /app/dist /opt/atrium/static/host
USER app
```
### 7. docker-compose.yml
Three services: `api`, `worker`, `mysql`. Both api and worker share the
host image (the worker overrides CMD to `python -m app.worker`).
Required env vars on **both** api and worker:
- `ATRIUM_HOST_MODULE=<your_pkg>.bootstrap`
- `PYTHONPATH=/app`
- `DATABASE_URL`, `JWT_SECRET`, `APP_SECRET_KEY`, `APP_BASE_URL`
- `WEBAUTHN_RP_ID`, `WEBAUTHN_RP_NAME`, `WEBAUTHN_ORIGIN`
- `MAIL_BACKEND`, `MAIL_FROM` (and `SMTP_*` if `MAIL_BACKEND=smtp`)
Disable healthcheck on the worker (`healthcheck: { disable: true }`) —
the shared image's HEALTHCHECK curls `/api/healthz`, which the worker
has no HTTP port for.
### 8. .env.example
Copy from [`README.md`](README.md) section *Step 7* and fill secrets
with placeholders. Tell the user to generate `APP_SECRET_KEY` and
`JWT_SECRET` with `openssl rand -hex 48`. Don't commit `.env` — only
`.env.example`.
### 9. First-boot ritual
After the user confirms they've filled in `.env`:
```bash
docker compose up -d --build
docker compose exec api alembic upgrade head # atrium migrations
docker compose exec api alembic -c /opt/host_app/alembic.ini upgrade head # host migrations
docker compose exec api python -m app.scripts.seed_admin \
--email <user-email> --password <password> \
--full-name '<Their Name>' --super-admin
```
Then write `system.host_bundle_url=/host/main.js` so atrium loads the
bundle. The simplest approach is to copy
[`examples/hello-world/backend/src/atrium_hello_world/scripts/seed_host_bundle.py`](../../examples/hello-world/backend/src/atrium_hello_world/scripts/seed_host_bundle.py)
into the host package as `<your_pkg>/scripts/seed_host_bundle.py` and
invoke:
```bash
docker compose exec api python -m <your_pkg>.scripts.seed_host_bundle /host/main.js
```
Or do it inline with the Python snippet in [`README.md`](README.md)
section *Step 8*.
### 9b. Backend tests in-container (optional)
The runtime image strips `pytest`, `pytest-asyncio`, and `httpx`. If the
host wants to run backend tests in the api container, install them on
demand or bake a `dev` Dockerfile stage. See [`README.md`](README.md)
section *Running backend tests in-container* for both patterns and a
Make target.
### 10. Verify
Open `http://localhost:8000`, log in with the seeded admin, and confirm
the registered widget(s) appear. If the bundle didn't load, check the
browser console for `[atrium] host bundle failed to load` (the SPA logs
the URL on failure). Common causes:
- `system.host_bundle_url` missing or wrong (run the seed script).
- Bundle path inside the image is wrong — should be at
`/opt/atrium/static/host/main.js` so atrium serves it at
`/host/main.js`.
- Bundle threw at import time — check `[your_pkg]` console errors;
usually `window.React` was undefined, meaning the bundle script ran
before atrium's main.tsx mounted (only happens if you `<script>`
the bundle directly instead of going through `host_bundle_url`).
## Retrofit cadence
When the user is bringing an existing app onto atrium (the
booking-app-casa case):
1. **Stand up the empty host repo first.** Do steps 1-9 above with a
single placeholder model + endpoint, prove the round-trip works
(login + bundle loads + endpoint reachable).
2. **Identify what atrium replaces.** Walk the existing codebase with
the user and tag every module as *delete* (atrium owns it) or
*port* (domain code). Concerns atrium owns: auth, RBAC, audit,
email pipeline, scheduled jobs, notifications, admin shell, theme,
i18n, maintenance mode, account deletion. Don't port any of those.
3. **Port models module-by-module** onto `HostBase`. Drop any
`users` / `roles` / `permissions` / `auth_sessions` / `email_*` /
`audit_log` / `scheduled_jobs` / `notifications` / `app_settings`
tables — atrium has them.
4. **Port routers**. Replace any custom auth middleware with
`Depends(current_user)` or `Depends(require_perm("..."))`.
5. **Port migrations as a single fresh `0001_init.py`.** Don't carry
the old chain over. Dump existing data with `mysqldump`, load it
after `alembic upgrade head` if needed.
6. **Port frontend pages as host-bundle exports.** Drop the existing
app shell — atrium ships header, sidebar, login, profile, admin
tabs. Keep the domain components and call them from
`registerRoute` / `registerNavItem` / `registerHomeWidget` /
`registerAdminTab`.
7. **Move config into atrium's KV.** Branding, feature flags,
translations, password policy, captcha config — move them into
`app_settings` namespaces (existing or new via
`register_namespace`). Anything secret stays in `.env`.
The retrofit is done when:
- Every route in the existing app either lives in
`<your_pkg>/router.py` or has been deleted because atrium covers it.
- Every page in the existing SPA is either a host-bundle registration
or has been deleted.
- All migrations are on the `alembic_version_app` chain; the old chain
is gone.
- Tests pass against the new shape.
## Reference: extension surface
```python
# Backend
from app.auth.users import current_user # auth required
from app.auth.rbac import require_perm # permission required
from app.auth.rbac_seed import seed_permissions_sync # in alembic migration
from app.auth.rbac_seed import seed_permissions # at runtime startup
from app.db import get_session, get_session_factory # async ORM session
from app.models.auth import User # User type
from app.services.audit import record as record_audit # write audit row
from app.services.notifications import notify_user # in-app notification + SSE
from app.services.app_config import register_namespace # admin-tunable namespace
from app.email.sender import send_and_log, enqueue_and_log # email pipeline
from app.host_sdk.worker import HostWorkerCtx # init_worker(host) ctx type
from app.settings import get_settings # env-var settings
from app.logging import log # structlog logger
```
```ts
// Frontend (window.__ATRIUM_REGISTRY__)
registerHomeWidget({ key, render })
registerRoute({ key, path, element, requireAuth?, layout? })
registerNavItem({ key, label, to, icon?, condition? })
registerNavGroup({ key, label, icon?, condition?, order?, children })
registerAdminTab({ key, label, icon?, perm?, section?, order?, render })
registerProfileItem({ key, slot?, render, condition? })
registerNotificationKind({ kind, render, title?, href? })
subscribeEvent(kind, (evt) => { /* qc.invalidateQueries(...) */ })
```
## Hard rules
- **Never edit atrium files.** Pin a tag, FROM the image, override
through extension points only.
- **Never share `Base` between host and atrium.** Use `HostBase`.
- **Cross-base FKs use `HostForeignKey`.** Column-level
`ForeignKey("users.id")` (or any atrium-table reference) on a
`HostBase` model fails at mapper-init — SQLAlchemy can't resolve
across metadata. Use `HostForeignKey("users.id", ondelete=...)`
from `app.host_sdk.db` and wire `emit_host_foreign_keys` from
`app.host_sdk.alembic` into the host's `alembic/env.py`. The
`ForeignKeyConstraint` then lands in autogenerated migrations
automatically. See `../host-models.md` for the full pattern.
- **Never use atrium's alembic version table.** Use
`alembic_version_app`.
- **Never bake secrets into the host bundle.** It's served public.
Authentication happens at API call time.
- **Never share React, MantineProvider, or QueryClient between atrium
and the bundle.** Two trees. The wrapper-div pattern is non-negotiable.
- **Never reimplement what atrium already ships** (auth, RBAC, audit,
email, jobs, notifications, admin shell, theme, i18n, maintenance,
account deletion). If a concern lives in atrium, the host's only job
is to call it.
## When to escalate
Stop and ask the user when:
- They want to use a different DB (atrium is hard-wired to MySQL 8 +
aiomysql).
- They want to ship a single-page app at a domain root that's not the
atrium SPA. The bundle pattern only handles fragments inside the
atrium shell. A standalone SPA is a separate concern (host project
fronts atrium's API at `/api/*` and serves its own SPA).
- They want to extend atrium's user model (e.g. add columns to
`users`). Atrium owns that table; host columns belong on a
per-user row in a host-side table joined by user_id.
- They want to override atrium's auth (e.g. SSO via OAuth/OIDC).
Atrium ships fastapi-users with cookies; an SSO front-end isn't a
host extension, it's a fork.
---
> Source: [brendanbank/atrium](https://github.com/brendanbank/atrium) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> Default to the scaffolder → Up-front decisions to confirm with the user → Procedure → 1. Repo skeleton → 2. Backend host package → 3. Alembic chain
terms -> Never edit atrium files · Example version-pinning. · at the matching git tag · Project / image name · Python module name · Atrium image pin · Public hostname + URL · Whether they're retrofitting an existing app
files/cmd -> ghcr.io/<org>/atrium:<X.Y> · FROM · README.md · ../../examples/hello-world/ · @brendanbank/atrium-host-* · frontend/src/main.tsx · Welcome* · examples/hello-world/
body sha256 -> 73cd3279cb6f
Default to the scaffolder
For a vanilla host (single Python module, single frontend bundle, the standard extension shape), run the scaffolder rather than emitting files by hand: The emitted repo wires every registry slot, ships CI, and uses the published
@brendanbank/atrium-host-*packages — itsfrontend/src/main.tsxUp-front decisions to confirm with the user
Before writing files, confirm: Project / image name (e.g.
bookings). Used as the docker image tag and project root. Python module name (e.g.bookings). Importable on PYTHONPATH; referenced byATRIUM_HOST_MODULE=<module>.bootstrap. Must notProcedure
Below,
<your-app>is the project name and<your_pkg>is the Python module name. Replace both consistently.1. Repo skeleton
Add a top-level
.gitignorecovering.env,node_modules,dist/,__pycache__/,.venv/,*.pyc.2. Backend host package
Create these files (full contents in
README.md, section Step 2):backend/pyproject.toml— hatchling, name<your-app>-host, no runtime deps (atrium image provides them).backend/src/<your_pkg>/__init__.py— empty marker.