Documentation
pocket-homeserver documentation
Everything to run the stack on a phone — 34 guides covering installation, day-to-day operations, the optional apps, and the advanced subsystems. Start with the setup guide, or search across every page.
/
No matches.
Getting started
2Core operations
7- Web admin panel A phone-friendly control panel: health, logs, restarts, backups, and a guarded danger zone.
- Matrix users Manage continuwuity users from the admin panel or CLI, wrapping the homeserver’s #admins command room.
- Backups & recovery The snapshot scripts under scripts/ops, retention rules, and the scheduled-backup daemon.
- Restore & rotation On-demand operator actions: restore from a snapshot and rotate credentials.
- Updating Every component is pinned by version + sha256 in config/versions.env; update.sh changes a pin safely instead of hand-editing.
- Observability & alerts An opt-in metrics sampler feeds the admin panel’s charts, plus a one-shot crash-loop alert — no inbound surface.
- Matrix bootstrap Idempotent helpers that seed a first admin, Spaces, and rooms after the homeserver is up.
Optional apps
10- Optional apps The core web-app suite — notes, tasks, status, bookmarks, feeds, search, dev tools, and file sharing — each gated by an ENABLE_ flag.
- App authentication How the optional web apps are protected and how to choose an auth model.
- Notes & wiki TriliumNext — a hierarchical notes / personal-wiki app with rich text, code notes, and full-text search at wiki.my.example.org.
- Calendar & contacts Radicale, a pure-Python CalDAV/CardDAV server that syncs calendars, contacts, and to-dos to DAVx5, Thunderbird, and iOS.
- Read-later Wallabag — save an article and keep a clean, tagged, searchable copy; reuses php-fpm, no composer install on the phone.
- Password manager Vaultwarden, a Bitwarden-compatible server that works with the official Bitwarden apps and browser extensions.
- Files & sync The personal-cloud tier: Dufs or FileBrowser over WebDAV plus peer-to-peer Syncthing — loopback-only, off by default.
- Media servers Three pinned, loopback-bound media servers — Navidrome (music), Kavita (comics/ebooks), and Audiobookshelf (audiobooks).
- Git forge A single-binary Gitea fork: repositories, issues, pull requests, releases, and git-over-HTTPS at git.my.example.org.
- Landing portal A Caddy-served service directory at your apex domain, generated from your ENABLE_* flags.
Advanced subsystems
12- Matrix SSO gateway Let users sign into the apps with their Matrix username and password; optional OIDC IdP.
- Chat bots Matrix bots that answer @-mentions via any OpenAI-compatible chat-completions endpoint.
- Sticker picker The Maunium stickerpicker widget plus a native backend for uploading custom stickers.
- Email backend A self-hosted mailbox (Maddy) fed by a Cloudflare Email Routing → R2 → drain pipeline; no open SMTP port.
- Webmail The email subsystem UI half: SnappyMail served by php-fpm, with optional Matrix SSO sign-in.
- Admin bot A private Matrix bot that lets only you drive the stack: status, users, invites, restarts.
- MCP server A Model Context Protocol server so an MCP client can observe and operate the stack.
- Honeypot An alert-only watcher that tails the Caddy access log and flags scanner traffic.
- Privacy & media filters Two loopback proxies in front of specific Matrix routes; off by default.
- AdGuard DNS A filtering DNS-over-HTTPS resolver published through the tunnel — point a device’s Private DNS at it (not a :53 sinkhole).
- Tailscale VPN Joins the phone to your WireGuard tailnet so your own devices reach it directly, bypassing CGNAT and the tunnel.
- BYO reverse proxy Publish a daemon you already run on 127.0.0.1:PORT on its own subdomain — a loopback-only Caddy vhost generator, no app script.
Reference
3- Security The threat model, the layered defenses that follow from it, and a deployment checklist.
- Resilience & recovery The failure modes a phone server faces — reboots, the low-memory killer, DB corruption — and the backoff, watchdog, and recovery that answer them.
- MCP server spec The MCP server design spec: transports, permission tiers, and threat model.