Spry/tools/spry/templates

{{APP_NAME}}

A Statum + Spry application, scaffolded by spry new.

Development

spry dev

Builds, runs the app on port 8080 (--port N to change) and watches src/, meson.build and web-config.json: saving a file rebuilds incrementally — page HTML and resources recompile via the meson codegen targets — and restarts the app when the build succeeds. A failed build keeps the previous process running while the compiler errors are shown. Restarts are cheap: Statum state is client-carried (the browser recovers transparently) and the static keys in web-config.json keep sessions alive — just refresh. --fresh starts from an empty database; --no-run builds once and exits.

The environment below is required for the underlying meson builds (the spry dev child processes set it for you; export it in shells where you build or run manually):

export WS_PREFIX="$HOME/.local"
export PKG_CONFIG_PATH="$WS_PREFIX/lib64/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
export XDG_DATA_DIRS="$WS_PREFIX/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS}"
export LD_LIBRARY_PATH="$WS_PREFIX/lib64${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

meson setup builddir
ninja -C builddir
./builddir/{{APP_NAME}}

The server listens on port 8080 (pass another port as the first argument). Static signing/encryption keys live in web-config.json (written by spry keys; gitignored and mode 0600 — never commit it or bake it into images), so sessions survive a restart. The SQLite store is ./{{APP_NAME}}.sqlite, or SPRY_DB_PATH when that variable is set.

An admin account is seeded on boot only when BOTH SPRY_SEED_ADMIN_USERNAME and SPRY_SEED_ADMIN_PASSWORD are set (the password is never logged); seeding is skipped silently otherwise:

export SPRY_SEED_ADMIN_USERNAME=admin
export SPRY_SEED_ADMIN_PASSWORD=change-me

Layout

Path	Purpose
src/main.vala	application wiring: modules, database, pages, actions
src/pages/*.html	Statum pages, compiled to Vala by statum-mkpstm at build time
src/entrypoints/	one StatumEntrypoint per page
src/actions/	StatumAction subclasses
src/resources/	static resources embedded by statum-mkres
web-config.json	static keys and other configuration (gitignored, 0600)

Registrations live between // spry:*-begin/end markers in src/main.vala, # spry:*-begin/end markers in meson.build and <!-- spry:nav-begin/end --> markers in src/pages/main.html (the layout's nav, plus the logged-in-only <!-- spry:nav-auth-begin/end --> block); the spry add commands edit only those blocks and are idempotent.

Growing the app

spry dev
spry add page <name> [--route /path]
spry add action <name>
spry add resource <file>
spry add login
spry add register
spry add user-management
spry keys
spry docker

add login, add register and add user-management also grow the layout nav (a Login/Register link when logged out, a Log-out button once login is added, a Users link for admins) inside the nav markers.

Docker

spry docker [--stack-dir <path>] [--tag <tag>] generates the multi-stage Dockerfile and .dockerignore. The Web-Stack trees carry fixes not on their remotes, so the image build COPYs every stack library from the local Web-Stack checkout: spry docker assembles the context itself (default stack dir: the app's sibling directory; override with --stack-dir). Only inversion is cloned inside the image, pinned to a reviewed commit. The context layout the Dockerfile expects is:

<context>/invercargill                ← Web-Stack/Invercargill
<context>/invercargill-json           ← Web-Stack/Invercargill-Json
<context>/astralis                    ← Web-Stack/astralis
<context>/invercargill-sql            ← Web-Stack/Invercargill-Sql
<context>/invercargill-sql-inversion  ← Web-Stack/Invercargill-Sql-Inversion
<context>/statum                      ← Web-Stack/Statum
<context>/spry                        ← Web-Stack/Spry
<context>/app                         ← this application

The base image is pinned by digest; refresh it with skopeo inspect docker://docker.io/library/fedora:43 and update both FROM lines. The inversion commit is pinned too — bump it in lockstep with the local checkout when it changes.

web-config.json is excluded from the build context (.dockerignore), so keys are never baked into the image: mount the config read-only at runtime and keep the SQLite store in the declared volume:

podman run -p 8080:8080 \
    -v $PWD/web-config.json:/app/web-config.json:ro \
    -v {{APP_NAME}}-data:/var/lib/{{APP_NAME}} \
    {{APP_NAME}}

To build by hand, recreate the layout above and run podman build -f Dockerfile -t {{APP_NAME}} <context>.