Daniel Maksymilian Syrnicki
8ed1d82fd3
Installs caddy + avahi + nss-mdns on the target and writes a small landing page, live status tiles (uptime / docker version / free disk via furtka-status.timer), and a console welcome banner — all via archinstall's custom_commands so the payload travels with the user_configuration.json. After reboot `http://<hostname>.local` serves a Furtka-branded page on :80 instead of the bare Arch login. No Authentik / no app store yet — demo shell for the real post- install work (Robert's area). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
139 lines
11 KiB
Markdown
139 lines
11 KiB
Markdown
# 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-outside-of-docker with host-mode jobs for ISO builds, setup captured in [docs/runner-setup.md](docs/runner-setup.md) + [ops/forgejo-runner/](ops/forgejo-runner/)
|
||
- [x] **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.
|
||
- [ ] **Publish `26.0-alpha` Forgejo Release** — blocker is gone (end-to-end install now works on a VM), re-tag when we're happy with the installer copy.
|
||
- [x] **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/`](iso/).
|
||
- [x] **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. Boot-USB filtering on bare metal is still TODO; see [iso/README.md](iso/README.md).
|
||
- [x] **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)`.
|
||
- [x] **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.
|
||
- [x] **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.
|
||
- [x] **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`. No Authentik / no app store yet — that's the next milestone (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` with a local CA (today: plain HTTP at `http://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.
|