Milestones 5 and 6: release workflow and deployment, store guide and assets #4

Merged
dawid merged 4 commits from deploy-plan into main 2026-11-16 04:59:16 +00:00
Owner

Milestones 5 and 6. This is stacked on #3, so merge #1, then #3, then this one. Nothing has been deployed, released or submitted.

Milestone 5: deployment and releases

Built as you decided (docs/deployment.md records the decisions):

  • address wristmark.apps.ciepiela.org;
  • CI deploys through Coolify's API, on tags only;
  • the viewer sleeps when unused;
  • the key comes later.

.forgejo/workflows/release.yml runs on vX.Y.Z, or by hand with a tag for a rollback:

  1. The release notes come from CHANGELOG.md's ## [X.Y.Z] section. Without one, the release fails rather than making notes up.
  2. The store package is built with tools/build-watch.sh --package (monkeyc --package-app --release), signed with CONNECTIQ_DEVELOPER_KEY (base64 of the DER key). The key goes to a temporary file that is deleted afterwards.
  3. The viewer's image is built and smoke-tested, and the files it serves are packed into a tarball.
  4. A Forgejo release is created with the .iq and the tarball (forgejo-release@v2). For a tag that already has a release, publishing is skipped: the action fails on an existing release (checked in its source), so the workflow asks the API first.
  5. The viewer is deployed through Coolify's API, pinned to the tag's commit, using the step from taschenrechner's working deploy workflow. The workflow then waits for the deployment and asks /healthz at the public address.

The viewer's Dockerfile gets a HEALTHCHECK; Docker reports the container healthy.

HomeLab #126 adds the homelab_apps entry, which gives this repository the deploy key and APPS_TOKEN. What's left after it, including creating the app in the panel by hand, is in docs/deployment.md, "What is left to do".

Milestone 6: store preparation

docs/publishing.md is the step-by-step guide. A research pass read Garmin's pages, and every step cites one. Where Garmin's docs are silent, the guide says not documented instead of guessing: the version field, screenshot specs, file limits, the update flow and beta testers. It covers:

  • the account: free for a free app;
  • the key: RSA 4096. "If you lose your original signing key you will not be able to update your app", so back it up twice;
  • the manifest settings;
  • sideloading, and the beta option (its own UUID, visible only to you);
  • building and uploading;
  • the listing assets, with Garmin's specs;
  • descriptions in English and German, which name no Garmin product, as Garmin's agreement requires;
  • the review rules that apply;
  • naming and trademarks;
  • privacy, review and updates;
  • a checklist.

Assets (docs/store-assets/):

  • the store icon, 500×500, and the on-device store icon, 128×128: marker 0 on #0055AA, a color in the 64-color palette Garmin asks for on MIP displays. They're generated by tools/generate-icon.mjs (with the launcher icon) and checked in CI. js-aruco2 detects ID 0 in all three icons.
  • the simulator screenshot from milestone 2.

Privacy page: viewer/public/privacy.html, in English and German, linked from the viewer. It says what stays in the browser and what the app host's proxy logs. Its contact is dawid@ciepiela.org; change it if you prefer another address.

Manifest: declares German as well. Garmin says the declared languages decide the store's regions. The only string, the app's name, needs no translation.

Please check

  • The name: Apple's App Store lists an iPhone app WristMark, a meeting recorder with a wrist app. My search found no trademark registration, but it doesn't replace a registry search; section 9 of the guide has the steps. Renaming is cheapest before the first upload.
  • Optional automatic releases: the release bot would tag wristmark weekly if the repository got a .cz.toml, like your other repositories. I didn't add one, because every release also needs the signing key and goes to the store.

Verified

  • viewer/test: 9 tests pass, including the privacy page under the CSP. The smoke test passes, and the container is healthy.
  • The store package builds with SDK 9.3.0 against a read-only SDK (a throwaway key, 8.8 KB for 1 device). The normal build passes with German declared.
  • The release notes extraction works on Keep a Changelog headings and drops link definitions.
  • actionlint finds nothing beyond Forgejo's URL-style uses: and the docker label.

Not verified

  • The release workflow has never run: there's no tag, key or panel app yet. Its first real run is your first tag.
  • The store's upload form, which Garmin doesn't document.

Update 2026-11-16: the name, the contact, the release bot

  • The store name is WristMarkCompanion, the repository wristmarkcompanion. The address stays wristmark.apps.ciepiela.org. The panel app must be named wristmarkcompanion, because the release workflow finds it by the repository name. HomeLab #126 is updated to match.
  • The privacy page and the store descriptions give contact@ciepiela.org.
  • .cz.toml is in: the release bot tags weekly, and the release workflow reads the bot's ## X.Y.Z - date sections.
  • Merge timing: once this is on main, the bot's next run tags v0.1.0. The release then fails until HomeLab #126 is deployed, the panel app exists and CONNECTIQ_DEVELOPER_KEY is set. Do those first, or rerun the release workflow by hand with the tag afterwards.
Milestones 5 and 6. This is stacked on #3, so merge #1, then #3, then this one. **Nothing has been deployed, released or submitted.** ## Milestone 5: deployment and releases Built as you decided (`docs/deployment.md` records the decisions): - address `wristmark.apps.ciepiela.org`; - CI deploys through Coolify's API, on tags only; - the viewer sleeps when unused; - the key comes later. **`.forgejo/workflows/release.yml`** runs on `vX.Y.Z`, or by hand with a tag for a rollback: 1. The release notes come from `CHANGELOG.md`'s `## [X.Y.Z]` section. Without one, the release fails rather than making notes up. 2. The store package is built with `tools/build-watch.sh --package` (`monkeyc --package-app --release`), signed with `CONNECTIQ_DEVELOPER_KEY` (base64 of the DER key). The key goes to a temporary file that is deleted afterwards. 3. The viewer's image is built and smoke-tested, and the files it serves are packed into a tarball. 4. A Forgejo release is created with the `.iq` and the tarball (`forgejo-release@v2`). For a tag that already has a release, publishing is skipped: the action fails on an existing release (checked in its source), so the workflow asks the API first. 5. The viewer is deployed through Coolify's API, pinned to the tag's commit, using the step from taschenrechner's working deploy workflow. The workflow then waits for the deployment and asks `/healthz` at the public address. The viewer's Dockerfile gets a `HEALTHCHECK`; Docker reports the container `healthy`. **HomeLab #126** adds the `homelab_apps` entry, which gives this repository the deploy key and `APPS_TOKEN`. What's left after it, including creating the app in the panel by hand, is in `docs/deployment.md`, "What is left to do". ## Milestone 6: store preparation **`docs/publishing.md`** is the step-by-step guide. A research pass read Garmin's pages, and every step cites one. Where Garmin's docs are silent, the guide says **not documented** instead of guessing: the version field, screenshot specs, file limits, the update flow and beta testers. It covers: - the account: free for a free app; - the key: RSA 4096. "If you lose your original signing key you will not be able to update your app", so back it up twice; - the manifest settings; - sideloading, and the beta option (its own UUID, visible only to you); - building and uploading; - the listing assets, with Garmin's specs; - descriptions in English and German, which name no Garmin product, as Garmin's agreement requires; - the review rules that apply; - naming and trademarks; - privacy, review and updates; - a checklist. **Assets** (`docs/store-assets/`): - the store icon, 500×500, and the on-device store icon, 128×128: marker 0 on `#0055AA`, a color in the 64-color palette Garmin asks for on MIP displays. They're generated by `tools/generate-icon.mjs` (with the launcher icon) and checked in CI. js-aruco2 detects ID 0 in all three icons. - the simulator screenshot from milestone 2. **Privacy page:** `viewer/public/privacy.html`, in English and German, linked from the viewer. It says what stays in the browser and what the app host's proxy logs. Its contact is `dawid@ciepiela.org`; change it if you prefer another address. **Manifest:** declares German as well. Garmin says the declared languages decide the store's regions. The only string, the app's name, needs no translation. ## Please check - **The name:** Apple's App Store lists an iPhone app **WristMark**, a meeting recorder with a wrist app. My search found no trademark registration, but it doesn't replace a registry search; section 9 of the guide has the steps. Renaming is cheapest before the first upload. - **Optional automatic releases:** the release bot would tag wristmark weekly if the repository got a `.cz.toml`, like your other repositories. I didn't add one, because every release also needs the signing key and goes to the store. ## Verified - `viewer/test`: 9 tests pass, including the privacy page under the CSP. The smoke test passes, and the container is `healthy`. - The store package builds with SDK 9.3.0 against a read-only SDK (a throwaway key, 8.8 KB for 1 device). The normal build passes with German declared. - The release notes extraction works on Keep a Changelog headings and drops link definitions. - actionlint finds nothing beyond Forgejo's URL-style `uses:` and the `docker` label. ## Not verified - The release workflow has never run: there's no tag, key or panel app yet. Its first real run is your first tag. - The store's upload form, which Garmin doesn't document. ## Update 2026-11-16: the name, the contact, the release bot - The store name is **WristMarkCompanion**, the repository `wristmarkcompanion`. The address stays `wristmark.apps.ciepiela.org`. The panel app must be named `wristmarkcompanion`, because the release workflow finds it by the repository name. HomeLab #126 is updated to match. - The privacy page and the store descriptions give `contact@ciepiela.org`. - `.cz.toml` is in: the release bot tags weekly, and the release workflow reads the bot's `## X.Y.Z - date` sections. - **Merge timing:** once this is on main, the bot's next run tags v0.1.0. The release then fails until HomeLab #126 is deployed, the panel app exists and `CONNECTIQ_DEVELOPER_KEY` is set. Do those first, or rerun the release workflow by hand with the tag afterwards.
docs: deployment and release proposal (milestone 5, for decision)
Some checks failed
CI / checks (pull_request) Has been cancelled
CI / e2e (pull_request) Has been cancelled
CI / image (pull_request) Has been cancelled
CI / watch (pull_request) Has been cancelled
e7a8b34997
The viewer on the app host's Coolify, deployed by CI through its API on tags
only, as the homelab's apps guide describes; health check, rollback, the two
address options, what the privacy page must say about the proxy's access log,
and the release workflow with the one secret it needs. Nothing set up.
On vX.Y.Z: the notes from CHANGELOG.md's section (none, no release), the
store package (build-watch.sh --package, signed with CONNECTIQ_DEVELOPER_KEY),
the viewer's image smoke-tested and its files packed, the Forgejo release,
and the viewer deployed through Coolify's API to wristmark.apps.ciepiela.org
with a health check. By hand with a tag it deploys that tag again. The
owner's decisions are recorded in docs/deployment.md.
feat: store preparation: the guide, the icons, the privacy page
All checks were successful
CI / checks (pull_request) Successful in 12s
CI / e2e (pull_request) Successful in 1m1s
CI / image (pull_request) Successful in 13s
CI / watch (pull_request) Successful in 15s
eb55fff6e0
docs/publishing.md walks through Garmin's store, checked against its
documentation on 2026-11-15, with what the documentation leaves open. The
store icons (500 and 128 px, marker 0 on a 64-color-palette blue) come from
generate-icon.mjs. The viewer's privacy page in English and German. German
declared in the manifest. Milestone 6, nothing submitted.
dawid changed title from docs: deployment and release proposal (milestone 5, for decision) to Milestones 5 and 6: release workflow and deployment, store guide and assets 2026-11-15 22:32:10 +00:00
dawid force-pushed deploy-plan from eb55fff6e0
All checks were successful
CI / checks (pull_request) Successful in 12s
CI / e2e (pull_request) Successful in 1m1s
CI / image (pull_request) Successful in 13s
CI / watch (pull_request) Successful in 15s
to 2668cc7e52
Some checks failed
CI / checks (pull_request) Has been cancelled
CI / e2e (pull_request) Has been cancelled
CI / image (pull_request) Has been cancelled
CI / watch (pull_request) Has been cancelled
2026-11-16 04:57:53 +00:00
Compare
dawid changed target branch from content-models to main 2026-11-16 04:58:23 +00:00
dawid force-pushed deploy-plan from 2668cc7e52
Some checks failed
CI / checks (pull_request) Has been cancelled
CI / e2e (pull_request) Has been cancelled
CI / image (pull_request) Has been cancelled
CI / watch (pull_request) Has been cancelled
to 9a27cc7189
All checks were successful
CI / checks (pull_request) Successful in 24s
CI / e2e (pull_request) Successful in 2m11s
CI / image (pull_request) Successful in 12s
CI / watch (pull_request) Successful in 13s
2026-11-16 04:58:57 +00:00
Compare
dawid merged commit 64b85d21b7 into main 2026-11-16 04:59:16 +00:00
dawid deleted branch deploy-plan 2026-11-16 04:59:17 +00:00
Sign in to join this conversation.
No description provided.