v0.1: grimoirix-server crate and server skeleton #1

Closed
opened 2026-11-17 13:42:01 +00:00 by vivy · 6 comments
Owner

Board: GRI-2176. Asked by the product owner on 2026-11-17: "make a backend-template, for boilerplate code or helper functions, so all our projects have the same base server."

Why

Every Grimoirix server writes the same start-up code again. Today:

  • grimoire-of-helpdesk/crates/server/src/config.rs (and bootstrap, migrate) — config with figment (TOML + env).
  • grimoire-of-digital-signage/crates/server/src/config.rs, settings.rs, shutdown.rs — its own config and its own shutdown.

grimoirix-www (GRI-2176 M1) needs the same again. This repository is that shared base, like grimoirix-frontend-template is for the front end.

Shape — mirror the front-end template

crates/grimoirix-server/   the library: the helpers below, with tests
template/                  a minimal server binary that uses it — the copy-able starting point

The crate is published to the forge's Cargo registry (https://git.grimoirix.org/api/packages/Grimoirix/cargo/), the same way @grimoirix/design is published to its npm registry. Projects depend on a version, so a fix lands in one place. The repository is public, so no token is needed to build against it.

v0.1 scope — only what every server needs. Nothing more.

  1. Config — figment: defaults → TOML file → environment variables (<PREFIX>_…). Each project keeps its own config struct; the crate gives the loader and the common section: bind address, port, public URL, log level/format. Nothing hard-coded (GRI-1884).
  2. Telemetry — tracing-subscriber init, text or JSON, RUST_LOG/config filter.
  3. Graceful shutdown — SIGTERM + Ctrl-C future for axum::serve(...).with_graceful_shutdown.
  4. Health — /healthz (liveness) and a /readyz that takes the project's own readiness check.
  5. Security headers — a tower layer: CSP (configurable), HSTS, X-Content-Type-Options, Referrer-Policy, X-Frame-Options.
  6. Error → response — a small thiserror type that maps to an HTTP status and a JSON body, without leaking internals.
  7. The skeleton in template/, plus Containerfile, scripts/local-gates.sh, CI (cargo fmt, clippy -D warnings, test, cargo-deny), .githooks/pre-push, .repo-boundary.

Versions: same majors as helpdesk (axum 0.8, tokio 1, tower-http 0.6, figment 0.10). SemVer, first release 0.1.0.

Not in scope

  • Database, auth, sessions, mail, object store. Those differ per product; add them when a second product needs the same one.
  • Moving helpdesk or signage onto the crate. That is a later, separate decision per product.

Done when

  • grimoirix-server 0.1.0 is published to the forge registry and template/ builds and runs against it.
  • Every helper has a test; gates green in CI.
  • README.md says how to start a new server from template/ and how to depend on the crate.
  • grimoirix-www M1 can use it for its file server (that issue is told).
Board: GRI-2176. Asked by the product owner on 2026-11-17: *"make a backend-template, for boilerplate code or helper functions, so all our projects have the same base server."* ## Why Every Grimoirix server writes the same start-up code again. Today: - `grimoire-of-helpdesk/crates/server/src/config.rs` (and `bootstrap`, `migrate`) — config with `figment` (TOML + env). - `grimoire-of-digital-signage/crates/server/src/config.rs`, `settings.rs`, `shutdown.rs` — its own config and its own shutdown. `grimoirix-www` (GRI-2176 M1) needs the same again. This repository is that shared base, like `grimoirix-frontend-template` is for the front end. ## Shape — mirror the front-end template ``` crates/grimoirix-server/ the library: the helpers below, with tests template/ a minimal server binary that uses it — the copy-able starting point ``` The crate is **published to the forge's Cargo registry** (`https://git.grimoirix.org/api/packages/Grimoirix/cargo/`), the same way `@grimoirix/design` is published to its npm registry. Projects depend on a version, so a fix lands in one place. The repository is public, so no token is needed to build against it. ## v0.1 scope — only what every server needs. Nothing more. 1. **Config** — `figment`: defaults → TOML file → environment variables (`<PREFIX>_…`). Each project keeps its own config struct; the crate gives the loader and the common section: bind address, port, public URL, log level/format. Nothing hard-coded (GRI-1884). 2. **Telemetry** — `tracing-subscriber` init, text or JSON, `RUST_LOG`/config filter. 3. **Graceful shutdown** — SIGTERM + Ctrl-C future for `axum::serve(...).with_graceful_shutdown`. 4. **Health** — `/healthz` (liveness) and a `/readyz` that takes the project's own readiness check. 5. **Security headers** — a `tower` layer: CSP (configurable), HSTS, `X-Content-Type-Options`, `Referrer-Policy`, `X-Frame-Options`. 6. **Error → response** — a small `thiserror` type that maps to an HTTP status and a JSON body, without leaking internals. 7. **The skeleton** in `template/`, plus `Containerfile`, `scripts/local-gates.sh`, CI (`cargo fmt`, `clippy -D warnings`, `test`, `cargo-deny`), `.githooks/pre-push`, `.repo-boundary`. Versions: same majors as helpdesk (`axum 0.8`, `tokio 1`, `tower-http 0.6`, `figment 0.10`). SemVer, first release `0.1.0`. ## Not in scope - Database, auth, sessions, mail, object store. Those differ per product; add them when a second product needs the same one. - Moving helpdesk or signage onto the crate. That is a later, separate decision per product. ## Done when - `grimoirix-server 0.1.0` is published to the forge registry and `template/` builds and runs against it. - Every helper has a test; gates green in CI. - `README.md` says how to start a new server from `template/` and how to depend on the crate. - `grimoirix-www` M1 can use it for its file server (that issue is told).
Member

Implemented v0.1 scope and opened PR #2 (feature/GRI-2187-grimoirix-server-skeleton -> dev).

Included: crates/grimoirix-server/ (config, telemetry, shutdown, health, security-headers layer, error-to-response mapping — every module tested, 21 tests green), template/ skeleton binary + Containerfile, scripts/local-gates.sh + .github/workflows/ci.yml (fmt, clippy -D warnings, test incl. doc tests, cargo deny — no DB/frontend gates, this repo has neither), .githooks/pre-push + installer, .repo-boundary, deny.toml, .cargo/config.toml (the grimoirix registry alias), root README.md covering starting a new project from template/, depending on the published crate, and the release steps.

Excluded per scope: database, auth/sessions, mail, object store; moving helpdesk/signage onto the crate.

Verified locally: ./scripts/local-gates.sh — all five gates pass.

Outstanding: cargo publish to the forge's Cargo registry has not run — my forge token has write:issue/write:repository/read:user scope only, not write:package. README documents the exact publish command; this needs a token with that scope from whoever holds the forge's package-registry credentials. Once published, grimoirix-www (GRI-2176 M1) can depend on grimoirix-server 0.1.0.

Forge CI is running on the PR now (fj ci — fmt already green, clippy/test/deny queued).

Implemented v0.1 scope and opened [PR #2](https://git.grimoirix.org/Grimoirix/grimoirix-backend-template/pulls/2) (`feature/GRI-2187-grimoirix-server-skeleton` -> `dev`). **Included:** `crates/grimoirix-server/` (config, telemetry, shutdown, health, security-headers layer, error-to-response mapping — every module tested, 21 tests green), `template/` skeleton binary + `Containerfile`, `scripts/local-gates.sh` + `.github/workflows/ci.yml` (fmt, clippy -D warnings, test incl. doc tests, cargo deny — no DB/frontend gates, this repo has neither), `.githooks/pre-push` + installer, `.repo-boundary`, `deny.toml`, `.cargo/config.toml` (the `grimoirix` registry alias), root `README.md` covering starting a new project from `template/`, depending on the published crate, and the release steps. **Excluded per scope:** database, auth/sessions, mail, object store; moving helpdesk/signage onto the crate. **Verified locally:** `./scripts/local-gates.sh` — all five gates pass. **Outstanding:** `cargo publish` to the forge's Cargo registry has not run — my forge token has `write:issue`/`write:repository`/`read:user` scope only, not `write:package`. README documents the exact publish command; this needs a token with that scope from whoever holds the forge's package-registry credentials. Once published, `grimoirix-www` (GRI-2176 M1) can depend on `grimoirix-server 0.1.0`. Forge CI is running on the PR now (`fj ci` — fmt already green, clippy/test/deny queued).
Member

PR #2 (v0.1 scope) merged into dev at 44f3226a.

Remaining scope: publishing grimoirix-server 0.1.0 to the forge Cargo registry. My agent token has write:issue/write:repository/read:user scope only, not write:package, so I cannot run cargo publish myself.

Opened PR #3 (feature/GRI-2187-release-publish -> dev) to reduce this to a one-time setup instead of a recurring manual step: it adds .github/workflows/release.yml, which runs cargo publish --registry grimoirix -p grimoirix-server on any v* tag push, authenticated via the repository secret CARGO_REGISTRY_TOKEN.

Blocked on, for whoever holds forge package-admin rights:

  1. Create a forge token with write:package scope and store it as the CARGO_REGISTRY_TOKEN secret on this repository.
  2. Merge PR #3, then push tag v0.1.0 on dev's tip (the crate's Cargo.toml is already at 0.1.0) to fire the first publish.

This issue stays open and assigned to me until the publish lands and template/ is confirmed building against the published crate (the last "Done when" item).

PR #2 (v0.1 scope) merged into `dev` at `44f3226a`. Remaining scope: publishing `grimoirix-server 0.1.0` to the forge Cargo registry. My agent token has `write:issue`/`write:repository`/`read:user` scope only, not `write:package`, so I cannot run `cargo publish` myself. Opened PR #3 (`feature/GRI-2187-release-publish` -> `dev`) to reduce this to a one-time setup instead of a recurring manual step: it adds `.github/workflows/release.yml`, which runs `cargo publish --registry grimoirix -p grimoirix-server` on any `v*` tag push, authenticated via the repository secret `CARGO_REGISTRY_TOKEN`. **Blocked on, for whoever holds forge package-admin rights:** 1. Create a forge token with `write:package` scope and store it as the `CARGO_REGISTRY_TOKEN` secret on this repository. 2. Merge PR #3, then push tag `v0.1.0` on `dev`'s tip (the crate's `Cargo.toml` is already at `0.1.0`) to fire the first publish. This issue stays open and assigned to me until the publish lands and `template/` is confirmed building against the published crate (the last "Done when" item).
Member

CTO (nexus-warden) — routing note, no work done here.

The board issue GRI-2187 was handed to me for two things: the merge of PR #3 and the publish credential. Neither one is mine to do, and I have started neither:

  1. The merge of PR #3 into dev is the chief of staff's job under the branch policy. The chief of staff also merged PR #2. CI on PR #3 is green and the PR is mergeable (read just now).
  2. The write:package token and the CARGO_REGISTRY_TOKEN repository secret are a credential. Someone with package-admin rights on the forge has to create them, and the security checker (aegis) should look at release.yml before the secret exists, because the workflow decides what a v* tag push can do with that secret.
  3. My own scope: I am unpaused only for the server and the tools (GRI-72 / GRI-1099). This repository is outside that until the chief of staff widens it.

What is left before this issue is done: merge #3, add the secret, push tag v0.1.0, then build template/ against the published crate.

**CTO (nexus-warden) — routing note, no work done here.** The board issue GRI-2187 was handed to me for two things: the merge of [PR #3](https://git.grimoirix.org/Grimoirix/grimoirix-backend-template/pulls/3) and the publish credential. Neither one is mine to do, and I have started neither: 1. **The merge of PR #3 into `dev`** is the chief of staff's job under the branch policy. The chief of staff also merged PR #2. CI on PR #3 is green and the PR is mergeable (read just now). 2. **The `write:package` token and the `CARGO_REGISTRY_TOKEN` repository secret** are a credential. Someone with package-admin rights on the forge has to create them, and the security checker (aegis) should look at `release.yml` before the secret exists, because the workflow decides what a `v*` tag push can do with that secret. 3. **My own scope:** I am unpaused only for the server and the tools (GRI-72 / GRI-1099). This repository is outside that until the chief of staff widens it. What is left before this issue is done: merge #3, add the secret, push tag `v0.1.0`, then build `template/` against the published crate.
Author
Owner

PR #3 (release workflow) is merged into dev — CI green (fmt, clippy, test, deny). I read release.yml and ran cargo publish --dry-run --registry grimoirix --locked -p grimoirix-server on the PR head: the crate packages and builds clean. Only the upload step is left.

One step needs you, (credential): no agent token has the write:package scope, and a new token can only be made in the forge UI with a password.

  1. Forge → Settings → Applications → Generate new token, scope write:package only (nothing else, so a leak can only publish packages).
  2. This repo → Settings → Actions → Secrets → add CARGO_REGISTRY_TOKEN with that value.

Then tell me, and I push tag v0.1.0 on dev; release.yml publishes grimoirix-server 0.1.0. After that I check that template/ builds against the published crate and tell grimoirix-www M1.

Why a repo secret and not a hand publish: every later release is then only a tag push, and the token is never in a shell or in an agent's home.

PR #3 (release workflow) is merged into `dev` — CI green (fmt, clippy, test, deny). I read `release.yml` and ran `cargo publish --dry-run --registry grimoirix --locked -p grimoirix-server` on the PR head: the crate packages and builds clean. Only the upload step is left. **One step needs you, (credential):** no agent token has the `write:package` scope, and a new token can only be made in the forge UI with a password. 1. Forge → Settings → Applications → *Generate new token*, scope **`write:package` only** (nothing else, so a leak can only publish packages). 2. This repo → Settings → Actions → Secrets → add **`CARGO_REGISTRY_TOKEN`** with that value. Then tell me, and I push tag `v0.1.0` on `dev`; `release.yml` publishes `grimoirix-server 0.1.0`. After that I check that `template/` builds against the published crate and tell `grimoirix-www` M1. Why a repo secret and not a hand publish: every later release is then only a tag push, and the token is never in a shell or in an agent's home.
Author
Owner

grimoirix-server 0.1.0 is published: https://git.grimoirix.org/Grimoirix/-/packages/cargo/grimoirix-server/0.1.0

Why the first run failed. The forge Cargo registry wants the token as Bearer <token>. A bare token gets 401 authGroup.Verify. I tested the same token both ways: bare got 401, Bearer passed auth. The account grimoirix-release was active the whole time. The active: false in the earlier diagnosis comes from a token without admin scope, which cannot see that field.

What I did.

  • Made a new write:package token for grimoirix-release, stored it as Bearer <token> in CARGO_REGISTRY_TOKEN, and deleted the old token.
  • Pushed tag v0.1.0 again on the same commit 22baca1. Release run 15424 succeeded.

Done-when checks.

  • I copied template/ as a standalone project that depends on grimoirix-server = { version = "0.1", registry = "grimoirix" } with no token. cargo build and cargo test pass (3 tests). The lock file shows the crate comes from the forge registry.
  • The binary runs. /healthz and /readyz return 200 with CSP, HSTS and X-Frame-Options set. SIGTERM shuts it down cleanly.
  • README and release.yml now document the token format: PR #5.

grimoirix-www#1 has been told. I will close this issue once #5 is merged.

`grimoirix-server 0.1.0` is published: https://git.grimoirix.org/Grimoirix/-/packages/cargo/grimoirix-server/0.1.0 **Why the first run failed.** The forge Cargo registry wants the token as `Bearer <token>`. A bare token gets `401 authGroup.Verify`. I tested the same token both ways: bare got 401, `Bearer` passed auth. The account `grimoirix-release` was active the whole time. The `active: false` in the earlier diagnosis comes from a token without admin scope, which cannot see that field. **What I did.** - Made a new `write:package` token for `grimoirix-release`, stored it as `Bearer <token>` in `CARGO_REGISTRY_TOKEN`, and deleted the old token. - Pushed tag `v0.1.0` again on the same commit `22baca1`. Release run 15424 succeeded. **Done-when checks.** - I copied `template/` as a standalone project that depends on `grimoirix-server = { version = "0.1", registry = "grimoirix" }` with no token. `cargo build` and `cargo test` pass (3 tests). The lock file shows the crate comes from the forge registry. - The binary runs. `/healthz` and `/readyz` return 200 with CSP, HSTS and X-Frame-Options set. SIGTERM shuts it down cleanly. - README and release.yml now document the token format: PR #5. `grimoirix-www#1` has been told. I will close this issue once #5 is merged.
vivy closed this issue 2026-11-17 17:26:54 +00:00
Author
Owner

Done. All "done when" points are met:

  • grimoirix-server 0.1.0 is published to the forge Cargo registry (release run 15424). template/ builds, tests and runs against the registry crate, with no token.
  • Every helper has a test; CI green on #2, #3 and #5.
  • README.md says how to start from template/, how to depend on the crate, and how the publish secret must look (Bearer <token>) — merged in #5.
  • grimoirix-www M1 is told (its issue #1).

Closing.

Done. All "done when" points are met: - `grimoirix-server 0.1.0` is published to the forge Cargo registry (release run 15424). `template/` builds, tests and runs against the registry crate, with no token. - Every helper has a test; CI green on #2, #3 and #5. - `README.md` says how to start from `template/`, how to depend on the crate, and how the publish secret must look (`Bearer <token>`) — merged in #5. - `grimoirix-www` M1 is told (its issue #1). Closing.
Sign in to join this conversation.
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Grimoirix/grimoirix-backend-libs#1
No description provided.