v0.1: grimoirix-server crate and server skeleton #1
Labels
No labels
Area/Backend
Area/Database
Area/Docs
Area/Frontend
Area/Infra
Area/Security
Area/Tests
Area/Tooling
Compat/Breaking
Kind/Bug
Kind/Documentation
Kind/Enhancement
Kind/Feature
Kind/Security
Kind/Testing
Lang/Python
Lang/Rust
Lang/Shell
Lang/SQL
Lang/TypeScript
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Reviewed
Confirmed
Reviewed
Duplicate
Reviewed
Invalid
Reviewed
Won't Fix
Routing
Auto
Routing
Hold
Routing
Human
Status
Abandoned
Status
Blocked
Status
Need More Info
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
Grimoirix/grimoirix-backend-libs#1
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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(andbootstrap,migrate) — config withfigment(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, likegrimoirix-frontend-templateis for the front end.Shape — mirror the front-end template
The crate is published to the forge's Cargo registry (
https://git.grimoirix.org/api/packages/Grimoirix/cargo/), the same way@grimoirix/designis 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.
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).tracing-subscriberinit, text or JSON,RUST_LOG/config filter.axum::serve(...).with_graceful_shutdown./healthz(liveness) and a/readyzthat takes the project's own readiness check.towerlayer: CSP (configurable), HSTS,X-Content-Type-Options,Referrer-Policy,X-Frame-Options.thiserrortype that maps to an HTTP status and a JSON body, without leaking internals.template/, plusContainerfile,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 release0.1.0.Not in scope
Done when
grimoirix-server 0.1.0is published to the forge registry andtemplate/builds and runs against it.README.mdsays how to start a new server fromtemplate/and how to depend on the crate.grimoirix-wwwM1 can use it for its file server (that issue is told).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(thegrimoirixregistry alias), rootREADME.mdcovering starting a new project fromtemplate/, 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 publishto the forge's Cargo registry has not run — my forge token haswrite:issue/write:repository/read:userscope only, notwrite: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 ongrimoirix-server 0.1.0.Forge CI is running on the PR now (
fj ci— fmt already green, clippy/test/deny queued).PR #2 (v0.1 scope) merged into
devat44f3226a.Remaining scope: publishing
grimoirix-server 0.1.0to the forge Cargo registry. My agent token haswrite:issue/write:repository/read:userscope only, notwrite:package, so I cannot runcargo publishmyself.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 runscargo publish --registry grimoirix -p grimoirix-serveron anyv*tag push, authenticated via the repository secretCARGO_REGISTRY_TOKEN.Blocked on, for whoever holds forge package-admin rights:
write:packagescope and store it as theCARGO_REGISTRY_TOKENsecret on this repository.v0.1.0ondev's tip (the crate'sCargo.tomlis already at0.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).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:
devis 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).write:packagetoken and theCARGO_REGISTRY_TOKENrepository secret are a credential. Someone with package-admin rights on the forge has to create them, and the security checker (aegis) should look atrelease.ymlbefore the secret exists, because the workflow decides what av*tag push can do with that secret.What is left before this issue is done: merge #3, add the secret, push tag
v0.1.0, then buildtemplate/against the published crate.PR #3 (release workflow) is merged into
dev— CI green (fmt, clippy, test, deny). I readrelease.ymland rancargo publish --dry-run --registry grimoirix --locked -p grimoirix-serveron 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:packagescope, and a new token can only be made in the forge UI with a password.write:packageonly (nothing else, so a leak can only publish packages).CARGO_REGISTRY_TOKENwith that value.Then tell me, and I push tag
v0.1.0ondev;release.ymlpublishesgrimoirix-server 0.1.0. After that I check thattemplate/builds against the published crate and tellgrimoirix-wwwM1.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.
grimoirix-server 0.1.0is published: https://git.grimoirix.org/Grimoirix/-/packages/cargo/grimoirix-server/0.1.0Why the first run failed. The forge Cargo registry wants the token as
Bearer <token>. A bare token gets401 authGroup.Verify. I tested the same token both ways: bare got 401,Bearerpassed auth. The accountgrimoirix-releasewas active the whole time. Theactive: falsein the earlier diagnosis comes from a token without admin scope, which cannot see that field.What I did.
write:packagetoken forgrimoirix-release, stored it asBearer <token>inCARGO_REGISTRY_TOKEN, and deleted the old token.v0.1.0again on the same commit22baca1. Release run 15424 succeeded.Done-when checks.
template/as a standalone project that depends ongrimoirix-server = { version = "0.1", registry = "grimoirix" }with no token.cargo buildandcargo testpass (3 tests). The lock file shows the crate comes from the forge registry./healthzand/readyzreturn 200 with CSP, HSTS and X-Frame-Options set. SIGTERM shuts it down cleanly.grimoirix-www#1has been told. I will close this issue once #5 is merged.Done. All "done when" points are met:
grimoirix-server 0.1.0is published to the forge Cargo registry (release run 15424).template/builds, tests and runs against the registry crate, with no token.README.mdsays how to start fromtemplate/, how to depend on the crate, and how the publish secret must look (Bearer <token>) — merged in #5.grimoirix-wwwM1 is told (its issue #1).Closing.