The application template¶

stackr's Copier template generates an application on artifactr, reflexr or both, wired to the stack's ports and nothing else: Supabase for sign-in and PostgreSQL, the gateway for models, the Collector for telemetry, and Langfuse for feedback and experiments (ADR-0004, ADR-0011, ADR-0015). Its questions are in copier.yml at the repository's root, and its files in template/.

Generate an application¶

uvx copier copy gh:alexnodeland/stackr my-app    # or a path to a clone of stackr
cd my-app
git init
make install        # uv sync, which writes uv.lock (commit it), and the git hooks
make env            # .env from .env.example
make check          # lint, types and tests, as its CI runs them

• Which version. Copier uses the template's latest release tag. stackr has none yet, so Copier warns that it found no tags and uses main. From a clone, --vcs-ref HEAD takes the checkout as it is, uncommitted changes included, which is how stackr's own checks render it.
• git init first. make install installs the git hooks, which need a repository, and stops with a message saying so when there is none; copier update later needs one with the generated files committed.
• No tasks. The template runs nothing on your machine as it generates, so it needs no --trust.

The questions¶

The libraries' revisions aren't questions: the template pins each library to the commit its code was written for (The libraries' revisions).

Answer non-interactively with --defaults and --data, as CI does:

uvx copier copy --defaults --data libraries=reflexr --data evals=false gh:alexnodeland/stackr my-app

Template questions lists every question with its choices, validation and the files each answer generates, and the values derived from them.

What it generates¶

Every surface is mounted under its library's name in every variant, so a variant, or a later copier update, never moves a URL, and both libraries mount side by side without clashing.

Settings¶

The application reads the stack's ports from its environment (settings.py); .env.example has every setting, with the stack's addresses on this machine:

The stack's two other ports, profiles and object storage, aren't read: nothing in a generated application profiles or stores objects yet. An application that adds them reads PYROSCOPE_SERVER_ADDRESS with a Pyroscope SDK, and the S3_* settings with an S3 client, with a bucket of its own (ADR-0005).

Fill in two things after make env: LITELLM_API_KEY, a tenant's key from make tenant NAME=acme in stackr (or LITELLM_TENANT_KEYS, a JSON object of a key per tenant), and LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY, from stackr's .env. Without a Langfuse public key, Langfuse is off; without OTEL_EXPORTER_OTLP_ENDPOINT, telemetry is off; without DATABASE_URL, workspaces live in memory.

Running it¶

The app profile is the application's own compose.yaml, not a service in stackr's. Its service joins the stackr network and local Supabase's, and reads stackr.env after .env, which replaces the stack's addresses in .env with their names on those networks. Its DATABASE_URL is local Supabase's PostgreSQL by name, unless STACK_DATABASE_URL in .env names another database.

So start the stack first, with local Supabase: stackr's default make up. The image is built in two stages, the first with git to fetch the libraries at their pinned commits, so building it needs the network.

Stopping: the server lets open requests finish for DRAIN. Then each library's MCP server stops, then its work, then its feedback mirrors, and the database closes last (ADR-0015). reflexr's reactor gives running actions STOP_GRACE to end, and records those it then cancels as abandoned attempts, which the next start retries (reflexr's graceful stop). artifactr's runner stops the agent's turns still going, each recording that it stopped (artifactr's serving guide). Together, and with the rest of the shutdown, they must end within the app profile's stop_grace_period.

The dev container is built on .devcontainer/compose.yaml. When the stack is running, its initialize.sh adds the stack's networks and stackr.env's addresses, so the application inside it reaches the stack by name; otherwise the dev container runs on its own.

Keeping it up to date¶

The template: copier update¶

uvx copier update

pulls in the template's improvements since the application was generated, keeping your own changes. It asks the questions again, with your previous answers (recorded in .copier-answers.yml) as the defaults; --skip-answered asks only the new ones. It needs a git repository with no uncommitted changes, and marks conflicts between the template's changes and yours inline, for you to resolve. Review the result like any other change, and run make check.

The libraries' revisions¶

artifactr and reflexr are pinned to commits in pyproject.toml's [tool.uv.sources] (ADR-0013). The pins are the template's, not answers, so copier update moves them with the template code written for them. evalr has no pin of its own: it comes with the libraries, at the commit their own [tool.uv.sources] pin.

To hold a library back, or try another commit, edit its rev there, then uv lock && make check. copier update keeps the edit, and marks a conflict when the template moves that pin or the other library's, on the line beside it.

In stackr: bumping the template's pins¶

The libraries install from GitHub rather than PyPI for now (artifactr#23), so the template's pins, artifactr_rev and reflexr_rev in copier.yml, follow each library's main by hand. make bump-libraries does it:

make bump-libraries                                  # every library, to the commit its main points to
make bump-libraries BUMP_FLAGS=--check               # change nothing; fail if a pin is behind main
make bump-libraries BUMP_FLAGS="artifactr=v0.1.0"    # artifactr only, to a tag, a branch or a commit SHA

It runs scripts/bump-libraries, which resolves each library's main with git ls-remote, rewrites the pins in copier.yml, regenerates the reference pages that show them (make docs-reference), and prints each pin it moved, with a link to what changed:

artifactr e890aca037c0 → 9c92a7f7685d  https://github.com/alexnodeland/artifactr/compare/e890aca037c0...9c92a7f7685d

Naming libraries moves only those; a commit SHA must be a full 40 characters, and is checked against the library's repository.

evalr moves when the libraries move their pins of it. When artifactr and reflexr pin different commits of evalr, uv lock fails in the Template jobs, naming both.

Then run make validate, and open a pull request with the output in its description: CI's template job generates every variant on the new revisions and runs its checks, and the smoke job runs an application on them beside the stack. When a library's main breaks the template, either fix the template in the same pull request, or pin that library to its last good commit.

Nothing runs this on a schedule, and CI doesn't run --check, which would fail every pull request as soon as a library merged something. Applications move to the new pins with copier update.

How the template is checked¶

• make validate renders all six variants (three choices of libraries, with and without evals) with scripts/check-template, under a name whose slug is the longest Copier accepts and whose package sorts before conftest, and checks that nothing is left unrendered, that the Python passes the generated project's own ruff settings, and that the YAML, shell scripts and Compose file pass their linters.
• CI's template job generates each variant, and the largest again on Python 3.14, and runs its own make check: lint, strict types, and the tests with 100% coverage.
• make smoke-app generates an application with both libraries and evals, runs it in its app profile beside the whole stack, and traces its agents through the gateway into Tempo and Langfuse (The smoke tests).

To render and check one variant locally:

uv run copier copy --defaults --vcs-ref HEAD --data libraries=both . /tmp/my-app
cd /tmp/my-app && git init && make install && make check