Daniel Maksymilian Syrnicki
9ae14f4108
Closes #9. New apps/README.md walks through the four-file contract (manifest.json, docker-compose.yaml, .env.example, icon.svg) with the rules enforced by furtka/manifest.py and the SVG sanitiser, using apps/fileshare as the reference. Root README: release list now covers 26.1/26.3/26.4 (26.2 stalled on the jq apt hang). Local HTTPS Phase 1 and the post-build smoke VM on pollux both flip to [x]; the old proksi.local HTTPS TODO becomes a Phase 2 entry (dedicated local CA + HTTPS on the live-installer wizard). iso/README: mDNS is wired — live ISO advertises proksi.local, installed box defaults to furtka.local (the form's default hostname, not proksi). HTTPS section notes Caddy tls internal on :443 shipped in 26.4 while the wizard itself is still HTTP. Overlay table picks up etc/hostname, etc/issue, furtka-update-issue, and furtka-issue.service. website/README: auto-deploy via .forgejo/workflows/deploy-site.yml is the default path now; website/deploy.sh stays as the SSH-hop fallback for off-CI pushes, and deploy-ci.sh is called out in the structure map. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
113 lines
4.8 KiB
Markdown
113 lines
4.8 KiB
Markdown
# 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/<name>/
|
||
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_<app>_<short>` 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_<app>_<short>` 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 `<script>`, `on*` attributes, and `javascript:` refs and enforces a 16 KB cap. Anything fancier than static paths and shapes will be rejected.
|
||
|
||
## Install and test
|
||
|
||
From the repo root on a dev box with Furtka installed:
|
||
|
||
```
|
||
sudo furtka app install ./apps/myapp
|
||
```
|
||
|
||
`furtka app install` runs a reconcile as its last step, so the container is up once the command returns. Open the Web UI (`http://furtka.local/`), fill in the settings form, and confirm the app starts. `docker ps` should show one container per compose service; `docker volume ls` should show `furtka_myapp_*`.
|
||
|
||
To bundle the app into the ISO, drop the folder into `apps/` before `iso/build.sh` runs — the build tarballs the whole `apps/` tree into the image.
|
||
|
||
## Out of scope (for now)
|
||
|
||
- Sharing volumes between apps. v1 keeps them isolated.
|
||
- Auth on the Web UI. The UI itself has a banner about this.
|
||
- Automatic updates. User-triggered per-app update is `POST /api/apps/<name>/update`.
|
||
- A network catalog. `furtka app install <name>` only resolves bundled apps in `/opt/furtka/apps/`.
|