diff --git a/README.md b/README.md index 7a09cbe..7f5d13d 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ None of these nail the "your dad can set this up" experience. The installer wiza - [x] Release process + CI — CalVer tags, conventional commits, Forgejo Actions (ruff, pytest, JSON, link checks), `26.0-alpha` tagged - [x] Forgejo runner live on Proxmox VM (`forge-runner-01`, Ubuntu 24.04) — docker-outside-of-docker with host-mode jobs for ISO builds, setup captured in [docs/runner-setup.md](docs/runner-setup.md) + [ops/forgejo-runner/](ops/forgejo-runner/) - [x] **ISO-build in CI** — `.forgejo/workflows/build-iso.yml` runs `iso/build.sh` on every push to `main` and publishes the resulting `.iso` as the `furtka-iso` artifact (14 d retention). Push → green run → download → test. -- [x] **Forgejo Releases + tag-driven release pipeline** — `.forgejo/workflows/release.yml` fires on `[0-9]*` tags, `scripts/build-release-tarball.sh` packages `furtka/` + `apps/` + `assets/` + a root VERSION, `scripts/publish-release.sh` uploads tarball + sha256 + release.json to the Forgejo releases page. `26.1-alpha` and `26.3-alpha` live at [releases](https://forgejo.sourcegate.online/daniel/furtka/releases). Needs one repo secret (`FORGEJO_RELEASE_TOKEN`). +- [x] **Forgejo Releases + tag-driven release pipeline** — `.forgejo/workflows/release.yml` fires on `[0-9]*` tags, `scripts/build-release-tarball.sh` packages `furtka/` + `apps/` + `assets/` + a root VERSION, `scripts/publish-release.sh` uploads tarball + sha256 + release.json to the Forgejo releases page. Releases `26.1-alpha`, `26.3-alpha`, and `26.4-alpha` live at [releases](https://forgejo.sourcegate.online/daniel/furtka/releases) (26.2 stalled on a `jq` apt hang, fixed in 26.3). Needs one repo secret (`FORGEJO_RELEASE_TOKEN`). - [x] **Walking-skeleton live ISO — end to end** — `iso/build.sh` produces a hybrid BIOS/UEFI Arch-based ISO. It boots in a Proxmox VM, DHCPs onto the LAN, shows a console welcome with `http://proksi.local:5000` (+ IP fallback), serves the Flask webinstaller, runs `archinstall --silent`, reboots the VM via a Reboot-now button, and the installed system logs in and runs `docker ps` without sudo. Build infra in [`iso/`](iso/). - [x] **Drop loop/rom devices from drive list** — `webinstaller/drives.py` filters by `lsblk` `TYPE=disk`, so the live squashfs and CD-ROM no longer appear as install targets. Boot-USB filtering on bare metal is still TODO; see [iso/README.md](iso/README.md). - [x] **Rebrand GRUB menu** — `iso/build.sh` rewrites "Arch Linux install medium" → "Furtka Live Installer" across GRUB, syslinux, and systemd-boot configs; default entry marked `(Recommended)`. @@ -117,8 +117,10 @@ None of these nail the "your dad can set this up" experience. The installer wiza - [x] **On-box web UI uplevel** — shared `/style.css` served by Caddy, persistent top nav, landing page with an "Your apps" tile grid + live status, `/apps` with real per-app icons (inlined SVG from each manifest), new `/settings` page (hostname, IP, version, kernel, RAM, Docker, uptime + Furtka-updates card). `prefers-color-scheme` light/dark. - [x] **Versioned on-box layout + Phase 1 per-app updates** — `/opt/furtka/versions//` + `current` symlink; `/var/lib/furtka/` for runtime state. `POST /api/apps//update` runs `docker compose pull` + compares digests + conditional `up -d`. - [x] **Phase 2 Furtka self-update** — `/settings` → Check → Update now. Downloads signed tarball (SHA256), stages, atomic symlink flip, reloads Caddy, daemon-reload, restarts services, health-checks the new api with auto-rollback on failure. CLI: `furtka update [--check]` + `furtka rollback`. Validated end-to-end on VM 2026-04-16 (`26.0-alpha` → `26.3-alpha` → rollback → reboot). +- [x] **Local HTTPS Phase 1** — Caddy `tls internal` on `:443` alongside plain `:80`. Per-box root CA generated on first start, `rootCA.crt` downloadable from `/settings`, per-OS install guide at `/https-install/`. Opt-in "force HTTPS" toggle only exposes itself once the current browser already trusts the cert, so enabling it can't lock the user out. Shipped in 26.4-alpha. +- [x] **Post-build smoke VM on Proxmox** — `.forgejo/workflows/build-iso.yml` hands the freshly built ISO to `scripts/smoke-vm.sh`, which boots it in a throwaway VM on `pollux` (192.168.178.165) and curls the webinstaller on `:5000`. VMID range 9000–9099, last 5 kept. Green end-to-end since 26.4-alpha. - [ ] Installer wizard screens S3–S7 — per-device purpose, network, domain, SSL, diagnostic. S5/S6 blocked on managed-gateway DNS infra not yet built. -- [ ] `https://proksi.local` with a local CA (today: plain HTTP at `http://proksi.local:5000`) +- [ ] Local HTTPS Phase 2 — dedicated local CA (not Caddy's `tls internal`), streamlined one-click install across Win/Mac/Linux/Android, and HTTPS on the live-installer wizard (`https://proksi.local:5000`). - [ ] Caddy + Authentik wired into first-boot bootstrap - [ ] Managed gateway infrastructure — `ns1/ns2.furtka.org` + DNS-01 wildcard automation - [ ] First containerized service (Nextcloud?) with auto-SSO + auto-subdomain diff --git a/apps/README.md b/apps/README.md new file mode 100644 index 0000000..13e750f --- /dev/null +++ b/apps/README.md @@ -0,0 +1,113 @@ +# Building a Furtka app from a Docker image + +A Furtka app is a folder with four files. The reconciler walks `/var/lib/furtka/apps/*` at boot, validates each manifest, ensures the declared volumes exist, and runs `docker compose up -d` per app. Filesystem is the only source of truth — no database. + +Use `apps/fileshare/` as the reference implementation. + +## Folder layout + +``` +apps// + manifest.json # required — app metadata and user-facing settings + docker-compose.yaml # required — filename is .yaml, not .yml + .env.example # required — keys consumed by docker-compose, with safe defaults + icon.svg # required — referenced by manifest.icon +``` + +The folder name must equal `manifest.name`. The scanner rejects mismatches. + +## `manifest.json` + +All top-level fields except `description_long` and `settings` are required. + +```json +{ + "name": "myapp", + "display_name": "My App", + "version": "0.1.0", + "description": "One-line summary shown in the app list.", + "description_long": "Longer German prose shown on the app page. Optional.", + "volumes": ["data"], + "ports": [8080], + "icon": "icon.svg", + "settings": [ + { + "name": "ADMIN_PASSWORD", + "label": "Passwort", + "description": "Wird beim ersten Start gesetzt.", + "type": "password", + "required": true + } + ] +} +``` + +Rules enforced by `furtka/manifest.py`: + +- `volumes` — short names, strings. Namespaced to `furtka__` at runtime. +- `ports` — integers. Informational only; compose owns the actual port binding. +- `settings[].name` — must match `^[A-Z_][A-Z0-9_]*$`. This name becomes both the env-var key and the form-field ID. +- `settings[].type` — one of `text`, `password`, `number`. +- `settings[].required` — if true, the install refuses when the value is empty. +- `settings[].default` — optional string. Used to pre-fill the form and the bootstrapped `.env`. + +## `docker-compose.yaml` + +- File extension is `.yaml`. The compose runner hardcodes this — `.yml` will not be found. +- Reference manifest volumes as `furtka__` with `external: true`. The reconciler creates the volume *before* `compose up`, so compose must not try to manage its lifecycle. +- Values from `.env` are substituted by compose in the usual `${VAR}` form. +- If the upstream image ships a HEALTHCHECK that misbehaves on Furtka's setup, disable it — a permanently-unhealthy container scares users reading `docker ps`. +- Pin images to a digest or stable tag when you can. `:latest` is acceptable for an MVP but noisy. + +Minimal example: + +```yaml +services: + app: + image: ghcr.io/example/myapp:1.2.3 + restart: unless-stopped + environment: + - ADMIN_PASSWORD=${ADMIN_PASSWORD} + ports: + - "8080:8080" + volumes: + - furtka_myapp_data:/var/lib/myapp + +volumes: + furtka_myapp_data: + external: true +``` + +## `.env.example` + +One `KEY=VALUE` per line. Every key declared in `manifest.settings` should have a line here so the compose file resolves cleanly on first install even before the user opens the form. + +Do not use `changeme` (or any value listed in `furtka.installer.PLACEHOLDER_SECRETS`) as the default for a required secret. The install step scans the final `.env` and refuses to finish if a placeholder survives — this is the guardrail that stops us shipping an app with a known password. + +For non-secret values (usernames, paths), sensible defaults are fine and go straight into `.env` on first install. + +## `icon.svg` + +- 64×64 viewBox, no width/height attributes so the UI can scale it. +- Use `fill="currentColor"` (and `stroke="currentColor"`) so the icon picks up the current theme instead of baking in a color. +- Keep it single-path-ish. These render small in the app grid. +- The icon is inlined into the `/apps` page by the defensive SVG sanitiser, which strips `