Files
artcraft-services/docs/linux-flatpak-oci.md
Dylan M. Taylor 8f2b99aae7 fix: repair Linux installation flows (#221)
## What changed

- Resolve the Flatpak OCI index digest from each real GHCR manifest
instead of manufacturing a digest. Use the actual launcher package path
(`storytold/craft-launcher`) and architecture-specific release tags.
- Vary Netlify's cache key by query string on both OCI index routes;
preserve architecture, repository, ref, and tag filtering.
- Return an explicit `503` if a referenced image is missing or
inaccessible. Document GHCR requirements and remove the distro test's
fallback that treated failed installs as success.
- Fix the `.flatpakref` download route, make all Linux distro tabs
reachable on mobile, make the Arch repo setup enable its config, and
change the advertised minimum to RHEL 10+.

## External release setup required

The current launcher OCI tags were pushed to
`ghcr.io/storytold/craft-launcher`, but anonymous token requests for
that package and the Craft app packages currently return `401`. Flatpak
clients cannot install private images. Set every package included in the
OCI index to **Public** in GHCR package settings before marking this PR
ready to merge. If the website needs authenticated index resolution
during that setup, configure the server-only `FLATPAK_OCI_READ_USERNAME`
and `FLATPAK_OCI_READ_TOKEN` variables; this does not replace public
package visibility for users.

## Validation

- `npm run typecheck` — passed.
- `npx playwright test tests/flatpak-oci.spec.ts` — 9 passed.
- Linux repository Playwright suite — 21 passed locally; the mobile
browser case could not launch locally because Chromium is unavailable.
The PR CI download suite passed all 35 browser tests, including the
mobile case.
- Live GHCR probe — current launcher and PdfCraft package token requests
return `401`; this is the release configuration blocker above.

The deploy preview confirms this: `/index/static?...` responds with
`503` and GHCR's `401` message. The existing `Flatpak OCI Remote` check
therefore fails until those packages are made public. The PR is
intentionally a draft while that external release setting is unresolved.

The initial Flatpak CI crash (`getFlatpakOciIndex().Results` on a
Promise) is fixed in the latest commit. The test helper now gets its
expected app IDs from the catalog without making registry requests. CI
should now reach and report the actual GHCR access failure described
above.
2026-11-01 16:32:34 -05:00

1.6 KiB

Linux Flatpak OCI registry

The website's Flatpak OCI index resolves each listed image tag against GHCR and returns the registry's real OCI manifest digest. The digest is required by Flatpak to pull the image and must never be generated from release metadata.

GHCR package setup

Every image referenced by the index must exist and be public so visitors can install it without credentials:

  • ghcr.io/storytold/craft-launcher (the shared release workflow uses the GitHub repository name)
  • ghcr.io/storytold/<app-slug> for each Craft app included in the website's OCI catalog

The release workflow publishes <version>-<architecture> and stable-<architecture> tags (for example, 0.12.0-x86_64 and stable-x86_64). After the first push for a package, set its GHCR package visibility to Public in the package settings. A private package can sometimes be read by the website with a server token, but Flatpak clients still cannot install it anonymously.

Optional website read token

Public GHCR packages normally allow anonymous index resolution. If the deployment needs an authenticated read, configure these server-only environment variables on the website deployment:

  • FLATPAK_OCI_READ_USERNAME: GitHub account that owns the token.
  • FLATPAK_OCI_READ_TOKEN: a token with read:packages access to the images.

Do not use NEXT_PUBLIC_ names or expose this token to browser code. This token only lets the website resolve manifest digests; it does not replace public package visibility for end-user installs. A missing tag or inaccessible image now causes the index request to return an error instead of publishing a fabricated digest.