furtka/apps

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.

{
  "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.

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

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:

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