71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
|
# furtka-apps
|
||
|
|
|
||
|
|
Apps catalog for [Furtka](https://furtka.org). Each release here ships a
|
||
|
|
tarball that running Furtka boxes pull via the daily catalog-sync timer
|
||
|
|
(see `furtka.catalog` in the core repo). Apps update on their own cadence,
|
||
|
|
independent of Furtka's core OS release schedule.
|
||
|
|
|
||
|
|
## Repo layout
|
||
|
|
|
||
|
|
```
|
||
|
|
apps/ # one folder per app
|
||
|
|
<name>/
|
||
|
|
manifest.json # JSON schema — see ./apps/README.md
|
||
|
|
docker-compose.yaml
|
||
|
|
.env.example # if the app has user-facing settings
|
||
|
|
icon.svg
|
||
|
|
scripts/
|
||
|
|
build-catalog-tarball.sh # bundle apps/ + VERSION into furtka-apps-<ver>.tar.gz
|
||
|
|
publish-catalog-release.sh # upload tarball + sha256 + release.json to Forgejo
|
||
|
|
validate-catalog.py # CI guardrail — manifest + compose syntax
|
||
|
|
vendor/
|
||
|
|
furtka_manifest.py # copy of daniel/furtka furtka/manifest.py
|
||
|
|
.forgejo/workflows/
|
||
|
|
ci.yml # JSON + manifest + shellcheck on every push/PR
|
||
|
|
release.yml # tag push → build tarball → publish to Forgejo releases
|
||
|
|
```
|
||
|
|
|
||
|
|
## Adding an app
|
||
|
|
|
||
|
|
See [apps/README.md](./apps/README.md) for the manifest schema, volume
|
||
|
|
namespacing rules, `.env.example` guardrails, and the SVG sanitiser
|
||
|
|
limits the Furtka UI enforces on `icon.svg`.
|
||
|
|
|
||
|
|
Shape of a new app PR:
|
||
|
|
|
||
|
|
1. Add `apps/<name>/` with all four files.
|
||
|
|
2. `python3 scripts/validate-catalog.py` locally — must go green.
|
||
|
|
3. Open a PR. CI runs the same validator + shellcheck.
|
||
|
|
4. Merged to `main` — next catalog release will include it.
|
||
|
|
|
||
|
|
## Cutting a release
|
||
|
|
|
||
|
|
Follows the same CalVer + tag-driven pattern as daniel/furtka:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Bump CHANGELOG.md [Unreleased] → [<version>] section, commit:
|
||
|
|
git commit -m "chore: release <version>"
|
||
|
|
git tag -a <version> -m "Release <version>"
|
||
|
|
git push origin main
|
||
|
|
git push origin <version>
|
||
|
|
```
|
||
|
|
|
||
|
|
Tag push fires `.forgejo/workflows/release.yml`. Needs
|
||
|
|
`FORGEJO_RELEASE_TOKEN` secret (PAT with `write:repository` on this repo).
|
||
|
|
|
||
|
|
## Trust model
|
||
|
|
|
||
|
|
Releases are unsigned (SHA256 sidecar only). Boxes verify the sidecar
|
||
|
|
against the downloaded tarball before extracting anything. Same posture
|
||
|
|
as daniel/furtka core releases — PGP is a deferred cross-repo migration.
|
||
|
|
|
||
|
|
## Relationship to daniel/furtka
|
||
|
|
|
||
|
|
- The core repo still ships `apps/fileshare/` as a seed inside the
|
||
|
|
Furtka release tarball. That's the offline/first-boot fallback.
|
||
|
|
- When a box has synced the catalog at least once, the resolver
|
||
|
|
(`furtka.sources.resolve_app_name`) prefers the catalog copy.
|
||
|
|
- Already-installed apps don't auto-reinstall on catalog updates — user
|
||
|
|
hits "Reinstall" in `/apps` when they want the new version. Settings
|
||
|
|
are merge-preserved.
|