furtka/docs/resource-manager.md

Resource Manager — Design Notes

Scaffold for the conversation between Daniel and Robert. Captures what Robert already sketched in chat on 2026-04-15 and lists the open questions that need an answer before we write code.

Status: Draft 2026-04-15. Nothing implemented. First app to consume this will be a LAN fileshare (SMB/NFS) — that's the forcing function.

---

What's the Resource Manager?

The layer between Furtka apps and the underlying system (disk, Docker, network, users). Apps don't touch Docker or the filesystem directly — they declare what they need, the Resource Manager provisions and tracks it.

Robert's framing (2026-04-15): "żeby później można było manipulować wszystkimi peryferiami" — so we can manipulate all peripherals from one place later.

---

Decided (Robert, 2026-04-15)

1. An app is a folder. A Furtka app is defined as a directory containing:
   • a manifest
   • a docker-compose.yaml
   • a .env file
2. A registration script reads that folder and wires the app into the backend.
3. Each app gets its own named Docker volume. Sharing between apps is possible but opt-in, not default.
4. Filesystem is the source of truth (for now). No SQL database yet — the Resource Manager reads current state from Docker and the OS ad-hoc. DB gets added when we actually need to store intent the OS doesn't know (e.g. "this share belongs to App X, readable by User Y").

These are locked; don't re-litigate without Robert.

---

Open questions

These need an answer before the first line of code.

Q1 — What's in the manifest?

This is the contract between app authors and Furtka. Changing it later is expensive. Known candidates:

• name (machine id, must match folder name?)
• display_name (shown in UI)
• version (semver? calver?)
• description
• volumes (list of named volumes the app needs)
• ports (which ports the app wants exposed; needed for reverse proxy later)
• icon (path or URL)
• ... anything else?

Format: YAML / TOML / JSON — not decided.

Q2 — Where do apps live on disk?

Suggested-but-not-decided: /var/lib/furtka/apps/<app-name>/. Robert: confirm path?

Q3 — What does the registration script actually do?

Robert said "Skript do rejestrowania w backendzie". Concretely that means some subset of:

• Validate manifest (schema check, required fields, volume names unique)
• Create any declared named volumes that don't exist yet
• Run docker compose up -d inside the app folder
• Record the app in whatever passes for the backend index (right now: nothing — we'd just re-scan the folder each time)

Sub-question: is registration a one-shot on install, or does something (systemd unit?) re-scan /var/lib/furtka/apps/ on every boot so the filesystem really is authoritative?

Q4 — How does the user actually install an app?

Out of scope for the first cut, but needed to know the shape of the CLI:

• Admin UI with a button "Install Fileshare"?
• CLI: furtka app install <tarball> / <git repo> / <name-from-catalog>?
• Catalog = a separate repo with app folders?

Q5 — Upgrades and removal

• Upgrade strategy: replace folder + re-run compose? Preserve volumes across upgrades (yes obviously, but needs stating)?
• Removal: does it delete the volume or keep it? Robert's "apki się dzielą" implies a volume can outlive its original app.

Q6 — Volume sharing semantics

Robert: "jak będzie trzeba to będą mogły się dzielić". Open:

• Who requests the share — the sharing app's manifest, or an admin action?
• What's the permission model (read-only, read-write, per-user)?
• This is probably the first piece of "intent not reflected in OS state" — might be what finally motivates the DB.

Q7 — Backend API surface

Once the filesystem model is clear, the Resource Manager's backend still needs some Python/whatever surface that the web UI and the register script both call. Rough shape:

• list_apps() — scan /var/lib/furtka/apps/, return manifests + running status
• install_app(folder) — validate + compose up
• remove_app(name) — compose down, optionally rm volume
• list_volumes() — from Docker
• list_shares() — ???

Not decided whether this lives in the existing webinstaller Flask app, a new backend service, or a thin CLI that the Flask app shells out to.

---

First consumer — Fileshare

The point of doing this now is to unblock the fileshare app (see ../memory/project_first_app_fileshare.md for the conversation context). Walking it through the model above:

/var/lib/furtka/apps/fileshare/
  manifest.???      # see Q1 — what exactly goes here?
  docker-compose.yaml
  .env

• App declares a volume (e.g. files).
• Compose runs a Samba/NFS container mounting that volume.
• On Mac/Windows/Android you mount smb://furtka.local/files.

If we can get this end-to-end through the Resource Manager, we've validated the whole model with the simplest possible app. Nextcloud, Jellyfin, etc. are the same shape with more knobs.

---

What we do NOT do yet

• No database. (Decided.)
• No user/permissions model beyond what Samba/OS already give us.
• No reverse proxy / TLS integration in the manifest. (Tracked separately — see ../memory/project_ssl_local_deferred.md.)
• No app catalog / store UI. Manual install first.
• No auto-updates.

These all become easier once Q1–Q7 are answered — adding them to an existing model is straightforward; guessing them now is expensive.