furtka-apps/apps/README.md

# 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`, `path`.
- `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`.

### Path-type settings (host bind mounts)

Use `"type": "path"` when the app should point at an existing folder on the host — media libraries, document archives, photo backups. The value is written to `.env` like any other setting, and compose consumes it via `${VAR}` substitution as a bind mount.

```json
{
  "name": "MEDIA_PATH",
  "label": "Medienordner",
  "description": "Absoluter Pfad zu deinem Medien-Ordner, z.B. /mnt/media.",
  "type": "path",
  "required": true
}
```

```yaml
services:
  app:
    volumes:
      - ${MEDIA_PATH}:/media:ro
```

The installer (`install_from` and `update_env`) refuses values that:

- aren't absolute (must start with `/`),
- don't exist on the host,
- aren't directories,
- resolve (after `Path.resolve()`) into a system-path deny-list: `/`, `/etc`, `/root`, `/boot`, `/proc`, `/sys`, `/dev`, `/bin`, `/sbin`, `/usr/bin`, `/usr/sbin`, `/var/lib/furtka`.

Traversal like `/mnt/../etc` is caught too — the deny-list check runs on the resolved path.

Path settings sit alongside manifest-declared volumes. Use `manifest.volumes` for internal state the app owns (databases, caches, config), and path settings for user data the container should mount and — usually — read without owning. Mounting read-only (`:ro`) is a good default for data the app only consumes.

## `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/`.