furtka/README.md

# Furtka

**Open-source home server OS — simple enough for everyone.** · [furtka.org](https://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](docs/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](https://casaos.io) | Layer on existing Linux | ~100 | Simplest install, runs on any distro |
| [Umbrel](https://umbrel.com) | Debian-based full OS | ~300 | Slick UI, crypto/privacy focus |
| [Runtipi](https://runtipi.io) | Docker-based, GPL-3.0 | 200+ | Largest default app catalog |
| [HomeDock OS](https://github.com/BansheeTech/HomeDockOS) | Pseudo-OS layer | Hundreds | Desktop-style UX with window manager |
| [Cosmos Server](https://github.com/azukaar/Cosmos-Server) | All-in-one platform | Docker | Built-in 2FA, anti-DDoS, security focus |
| [YunoHost](https://yunohost.org) | Debian-based OS (since 2012) | 400+ | Most mature, biggest catalog |
| [TurnKey Linux](https://www.turnkeylinux.org) | Pre-built system images | Hundreds | One image per use case |

### Recent signals (from [competitors.md](docs/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](https://github.com/getumbrel/umbrel/issues/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](https://github.com/IceWhaleTech/CasaOS/discussions/2386) 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](https://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

- [x] Installer webapp prototype — device reader + form → JSON (Robert)
- [x] Arch running on Proxmox, custom image builds in progress (Robert)
- [x] Competitor analysis — see [docs/competitors.md](docs/competitors.md)
- [x] Wizard flow spec — see [docs/wizard-flow.md](docs/wizard-flow.md)
- [x] Release process + CI — CalVer tags, conventional commits, Forgejo Actions (ruff, pytest, JSON, link checks), `26.0-alpha` tagged
- [x] Forgejo runner live on Proxmox VM (`forge-runner-01`, Ubuntu 24.04, Docker + DinD sidecar) — setup captured in [docs/runner-setup.md](docs/runner-setup.md) + [ops/forgejo-runner/](ops/forgejo-runner/)
- [ ] **Publish `26.0-alpha` Forgejo Release** — deferred. Walking-skeleton ISO boots but doesn't install yet; re-tag once `archinstall` actually completes end-to-end on a VM.
- [x] **Walking-skeleton live ISO** — `iso/build.sh` produces a hybrid BIOS/UEFI Arch-based ISO that boots in a Proxmox VM, DHCP's onto the LAN, and serves the Flask webinstaller on `:5000`. Screens 1–3 work end-to-end. Build infra in [`iso/`](iso/).
- [x] **Drop loop/rom devices from drive list** — `webinstaller/drives.py` now filters by `lsblk` `TYPE=disk`, so the live squashfs and CD-ROM no longer appear as install targets.
- [x] **Rebrand GRUB menu** — `iso/build.sh` rewrites "Arch Linux install medium" → "Furtka Live Installer" across GRUB, syslinux, and systemd-boot configs.
- [x] **S1 account form + 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`, log page polls output. `FURTKA_DRY_RUN=1` skips the exec for testing.
- [ ] **Base OS post-install** — what Furtka actually looks like *after* the wizard writes config + reboots: Caddy + Authentik + app store. Robert's area.
- [ ] Installer wizard screens S3–S7 — per-device purpose, network, domain, SSL, diagnostic. S5/S6 blocked on managed-gateway DNS infra not yet built.
- [ ] `https://proksi.local` via mDNS + local CA (currently only raw-IP HTTP)
- [ ] 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.