furtka/README.md

Furtka

Open-source home server OS — simple enough for everyone. · furtka.org

"Furtka" is Polish for gate — a play on the gateway concept (reverse proxy + DNS as your home's front door).

Turn any x86 PC into a powerful, self-hosted home server with an app-store experience. No terminal skills required.

Vision

People are tired of big companies knowing everything about them. Synology NAS comes close to solving this, but it's expensive and still too complicated for most people.

Furtka aims to be:

• As easy to install as Windows — boot from USB, click through a wizard, done
• As easy to use as an app store — want Nextcloud? Click install, pick a name, wait a few minutes, and you have nextcloud.yourdomain.de
• Container-based — everything runs in Docker, with sensible default configs
• Built for normal people — your dad should be able to run his own cloud server
• Fully open source — with an optional support/infrastructure subscription (Proxmox model)

Principles

• Everything already exists — We're not inventing, we're connecting. Docker, reverse proxies, Let's Encrypt — it all works. We just wire it together with default configs and a simple wrapper.
• Dogfooding — We build what we use ourselves. If we wouldn't run it at home, we don't ship it.
• Two-tier UX — Dead simple for beginners (click Install, done), full control for advanced users (SSH in, edit configs, do whatever you want).

Architecture

+------------------+
|   Web UI         |  <- Simple admin panel / app store
+------------------+
|   Settings       |  <- UI/API wrapper that generates Docker configs
|   Wrapper        |     from simple user choices
+------------------+
|   Docker         |  <- Containers with sensible default configs
+------------------+
|   Gateway        |  <- Reverse proxy, SSL, DNS (self-hosted or managed)
+------------------+
|   Base OS        |  <- Minimal Linux (leaning Arch, Debian as fallback)
+------------------+
|   Any x86 HW     |  <- Old PC, mini PC, NUC, whatever
+------------------+

Key Decisions

Decision	Status	Notes
Base OS	Leaning Arch	Robert already has Arch running on Proxmox and is building custom images. Debian remains fallback (FAI, Proxmox ecosystem).
Containers	Docker	Lower overhead than VMs, easier default configs
Installation	Web-based wizard	Robert's webapp prototype (device reader + form → JSON) is working. Full spec: wizard-flow.md
Reverse proxy	Caddy	Automatic Let's Encrypt, simplest config of any reverse proxy
Identity provider	Authentik	Bundled SSO from day one — every app template auto-wires to it at install
Managed gateway DNS	NS delegation to ns1.furtka.org	User delegates once at registrar; we handle wildcard cert + subdomain creation
Local HTTPS	Local CA	One-click CA install → green padlock on every service, no browser warnings
Gateway	Flexible	Own reverse proxy OR managed through our infrastructure
UI approach	UI-first	Design the simplest possible UI, then build everything to match

Landscape (Existing Projects)

Project	Type	Apps	Key Trait
CasaOS	Layer on existing Linux	~100	Simplest install, runs on any distro
Umbrel	Debian-based full OS	~300	Slick UI, crypto/privacy focus
Runtipi	Docker-based, GPL-3.0	200+	Largest default app catalog
HomeDock OS	Pseudo-OS layer	Hundreds	Desktop-style UX with window manager
Cosmos Server	All-in-one platform	Docker	Built-in 2FA, anti-DDoS, security focus
YunoHost	Debian-based OS (since 2012)	400+	Most mature, biggest catalog
TurnKey Linux	Pre-built system images	Hundreds	One image per use case

Recent signals (from competitors.md)

• Umbrel's license is the #1 r/selfhosted complaint. PolyForm Noncommercial 1.0.0 isn't OSI-approved; Citadel forked explicitly over this.
• Umbrel has refused HTTPS on its local UI for 4+ years. Issue #546 open since Feb 2021. Community quote: "all it takes is one Umbrel vuln to bring down half of the lightning network."
• CasaOS is in maintenance mode. IceWhale pivoted focus to ZimaOS (paid hardware). Users are openly asking if the project is still alive.

Where we differentiate

1. Full OS + device-aware installer wizard — Boot USB, open https://proksi.local, wizard detects hardware and configures everything. No existing project does this — CasaOS/HomeDock are layers on existing Linux, Umbrel's x86 installer asks you to type a drive number, YunoHost runs stock Debian partitioning.
2. Auto setup intelligence — Tests drive speeds, auto-assigns boot/LVM storage. Competitors just ask you to pick a drive.
3. Gateway-as-a-service — No competitor offers managed reverse proxy + DNS + SSL as a service. Even YunoHost (best SSL story of the three) punts DNS setup to the user's registrar — that's the UX cliff where newbies quit.
4. HTTPS + AGPL from day one — HTTPS on the local UI via a one-click local CA install (no browser warnings, unlike YunoHost's self-signed model). Fully AGPL-3.0 — the exact counter-position to Umbrel's non-OSI license complaints.

Gap we're targeting

None of these nail the "your dad can set this up" experience. The installer wizard + managed gateway + HTTPS-by-default is the strongest angle.

Resources

• awesome-docker-compose.com — Ready-made Docker Compose configs (useful later for app store defaults)

Inspiration

• Azure Local — cluster management for enterprises, we want this for home users
• Proxmox community-scripts — great base, but VM-focused (more overhead)
• Synology DSM — closest to our UX goal, but proprietary and expensive
• Home Assistant — app-store model for smart home, we want this for all services

Roadmap

• Installer webapp prototype — device reader + form → JSON (Robert)
• Arch running on Proxmox, custom image builds in progress (Robert)
• Competitor analysis — see docs/competitors.md
• Wizard flow spec — see docs/wizard-flow.md
• Release process + CI — CalVer tags, conventional commits, Forgejo Actions (ruff, pytest, JSON, link checks), 26.0-alpha tagged
• Forgejo runner live on Proxmox VM (forge-runner-01, Ubuntu 24.04) — docker-outside-of-docker with host-mode jobs for ISO builds, setup captured in docs/runner-setup.md + ops/forgejo-runner/
• ISO-build in CI — .forgejo/workflows/build-iso.yml runs iso/build.sh on every push to main and publishes the resulting .iso as the furtka-iso artifact (14 d retention). Push → green run → download → test.
• Forgejo Releases + tag-driven release pipeline — .forgejo/workflows/release.yml fires on [0-9]* tags, scripts/build-release-tarball.sh packages furtka/ + apps/ + assets/ + a root VERSION, scripts/publish-release.sh uploads tarball + sha256 + release.json to the Forgejo releases page. Releases 26.1-alpha, 26.3-alpha, and 26.4-alpha live at releases (26.2 stalled on a jq apt hang, fixed in 26.3). Needs one repo secret (FORGEJO_RELEASE_TOKEN).
• Walking-skeleton live ISO — end to end — iso/build.sh produces a hybrid BIOS/UEFI Arch-based ISO. It boots in a Proxmox VM, DHCPs onto the LAN, shows a console welcome with http://proksi.local:5000 (+ IP fallback), serves the Flask webinstaller, runs archinstall --silent, reboots the VM via a Reboot-now button, and the installed system logs in and runs docker ps without sudo. Build infra in iso/.
• Drop loop/rom devices from drive list — webinstaller/drives.py filters by lsblk TYPE=disk, so the live squashfs and CD-ROM no longer appear as install targets. The boot USB itself is also filtered: on the live ISO, findmnt /run/archiso/bootmnt resolves the boot partition and its parent disk is dropped from the picker.
• Rebrand GRUB menu — iso/build.sh rewrites "Arch Linux install medium" → "Furtka Live Installer" across GRUB, syslinux, and systemd-boot configs; default entry marked (Recommended).
• Wizard: account form → drive picker → overview → archinstall — S1 collects hostname/user/password/language with validation, S2 picks boot drive, overview confirms, /install/run writes user_configuration.json + user_credentials.json (0600) and execs archinstall --silent against its 4.x schema (default_layout disk_config + !root-password / !password sentinel keys + custom_commands for post-install group joins). Install log page polls a JSON endpoint and renders a phase-based progress bar with a collapsible raw log. FURTKA_DRY_RUN=1 skips the real exec for testing.
• mDNS proksi.local — hostname baked into the live ISO, avahi + nss-mdns in the package list, advertised as soon as network-online fires. The HTTPS + local-CA half of this milestone is still open below.
• Base OS post-install (demo level) — after reboot the installed system comes up with Caddy on :80 serving a Furtka landing page (welcome + live uptime/Docker/disk tiles), the console shows a banner pointing at http://<hostname>.local, and nss-mdns makes that URL resolve on the LAN. Written by webinstaller/app.py's _post_install_commands via archinstall's custom_commands.
• Resource manager + first bundled app (fileshare/SMB) — furtka/ Python package handles scan / install / remove / reinstall of apps shipped under apps/. Manifest schema with settings fields drives an in-browser config form (no SSH needed). First app is a dperson/samba share mountable from Mac/Win/Linux. Validated end-to-end on VM 2026-04-16.
• On-box web UI uplevel — shared /style.css served by Caddy, persistent top nav, landing page with an "Your apps" tile grid + live status, /apps with real per-app icons (inlined SVG from each manifest), new /settings page (hostname, IP, version, kernel, RAM, Docker, uptime + Furtka-updates card). prefers-color-scheme light/dark.
• Versioned on-box layout + Phase 1 per-app updates — /opt/furtka/versions/<ver>/ + current symlink; /var/lib/furtka/ for runtime state. POST /api/apps/<name>/update runs docker compose pull + compares digests + conditional up -d.
• Phase 2 Furtka self-update — /settings → Check → Update now. Downloads signed tarball (SHA256), stages, atomic symlink flip, reloads Caddy, daemon-reload, restarts services, health-checks the new api with auto-rollback on failure. CLI: furtka update [--check] + furtka rollback. Validated end-to-end on VM 2026-04-16 (26.0-alpha → 26.3-alpha → rollback → reboot).
• Local HTTPS Phase 1 — Caddy tls internal on :443 is fully opt-in via the /settings toggle (26.15-alpha); fresh installs stay HTTP-only so a half-trusted cert chain can't lock the user out. Per-box root CA generated on first enable, rootCA.crt downloadable from /settings, per-OS install guide at /https-install/. The "force HTTPS" sub-toggle still only appears once the current browser already trusts the cert.
• Post-build smoke VM on Proxmox — .forgejo/workflows/build-iso.yml hands the freshly built ISO to scripts/smoke-vm.sh, which boots it in a throwaway VM on pollux (192.168.178.165) and curls the webinstaller on :5000. VMID range 9000–9099, last 5 kept. Green end-to-end since 26.4-alpha.
• Installer wizard screens S3–S7 — per-device purpose, network, domain, SSL, diagnostic. S5/S6 blocked on managed-gateway DNS infra not yet built.
• Local HTTPS Phase 2 — dedicated local CA (not Caddy's tls internal), streamlined one-click install across Win/Mac/Linux/Android, and HTTPS on the live-installer wizard (https://proksi.local:5000).
• Caddy + Authentik wired into first-boot bootstrap
• Managed gateway infrastructure — ns1/ns2.furtka.org + DNS-01 wildcard automation
• First containerized service (Nextcloud?) with auto-SSO + auto-subdomain
• Competitor hands-on testing on Proxmox — validate findings from docs/competitors.md
• UI mockups / drafts (Robert)

Business Model

Furtka starts as a private/personal project. The long-term model follows Proxmox:

• Free & open source — anyone can download, install, and use it
• Paid support & managed infrastructure — for users who want hassle-free setup
• Managed gateway option — the gateway (reverse proxy, SSL, DNS) can be self-hosted or run through our managed infrastructure (potential subscription revenue)

Team

• Robert — Architecture, UI design, webapp installer prototype
• Daniel — Infrastructure, testing, DevOps

License

AGPL-3.0 — open source, community-driven.