114 lines
4.8 KiB
Markdown
114 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/`.
|