HomeServerHQ

HomeServerHQ (HSHQ) is a turnkey, self‑hosted infrastructure stack that abstracts the complexities of building a home network with modern security practices. From a developer’s perspective, HSHQ bundles a WireGuard‑based VPN, an internal OpenSSL/Caddy certificate authority, and Authelia for fine‑grained authentication. The result is a private “internet” that exposes services—web, mail, file sharing—without opening any router ports. The core engine is a lightweight shell script (hshq.sh) that orchestrates the deployment of Docker containers and system services, allowing rapid iteration while preserving a declarative configuration model.

Architecture

• Operating System: Debian/Ubuntu‑based distributions (Bookworm, Jammy, Noble) with optional Mint support.
• Container Runtime: Docker Engine (or Podman‑compatible), ensuring isolated service boundaries.
• Service Orchestration: A custom hshq.sh bootstrap script that pulls a curated set of Docker images (Caddy, Authelia, Postfix, MariaDB, etc.) and configures them via templated docker‑compose.yml files.
• Networking: Dual‑layer VPN—WireGuard for the perimeter, and an internal TLS mesh managed by Caddy’s ACME integration.
• Authentication: Authelia with LDAP/SQL backends, exposing OAuth2 and SAML endpoints for third‑party integrations.
• Storage: Local ext4 or XFS filesystems exposed to containers via Docker volumes; optional integration with NAS/S3 for persistent backups.

Core Capabilities

• API Surface: Each service exposes a RESTful API (e.g., Caddy’s JSON admin API, Authelia’s OAuth endpoints). HSHQ also provides a lightweight GraphQL shim for orchestrating service health and configuration.
• Webhook Support: Built‑in Webhook endpoints trigger on DNS updates, certificate renewals, or service restarts, enabling CI/CD pipelines to react in real time.
• Plugin System: The hshq framework reads /opt/hshq/plugins/*.sh, allowing developers to inject custom scripts that run during installation or at scheduled intervals.
• Custom ISO Builder: The project ships a build system that compiles a minimal Debian image with pre‑installed hshq.sh, simplifying headless deployments on ARM or x86 hardware.

Deployment & Infrastructure

• Self‑Hosting Requirements: A single machine (≥2 GB RAM, 20 GB SSD) suffices for a basic installation; scaling to multiple homes uses HSHQ’s RelayServer concept—an outbound VPS that acts as a NAT‑traversal gateway for WireGuard.
• Scalability: Docker’s layered images allow horizontal scaling of stateless services (e.g., adding more Caddy instances behind a reverse‑proxy). Stateful components such as databases can be replicated using Galera or Patroni for high availability.
• Containerization: All services are shipped as Docker images; developers can override environment variables or mount custom configuration files via docker‑compose.override.yml.
• Infrastructure Automation: HSHQ’s shell scripts are idempotent, making them suitable for Ansible or Terraform provisioning. The project also offers a Helm chart for Kubernetes‑native deployments, exposing the same service definitions in a cluster.

Integration & Extensibility

• Plugin SDK: The hshq-plugin interface exposes lifecycle hooks (pre‑install, post‑install, on‑update). Developers can author Bash modules that register new services or modify network topology.
• Webhooks & API: External systems can listen to HSHQ events via POST /webhook/*. For example, a GitHub Action can trigger a DNS record update after pushing to a repository.
• Custom Domains: HSHQ automatically generates TLS certificates for user‑supplied domains using Caddy’s ACME client, allowing seamless integration with existing domain registrars via API.
• Extensible Service Catalog: The hshq.sh script pulls from a central manifest (services.yaml) where developers can add new containers, define health checks, and specify resource limits.

Developer Experience

• Configuration: All settings reside in /opt/hshq/config/*.yaml, with clear comments. The system supports both YAML and JSON, catering to tooling preferences.
• Documentation: The official wiki (https://wiki.homeserverhq.com) contains a dedicated “Developer” section with API references, plugin tutorials, and architecture diagrams.
• Community & Support: An active GitHub Discussions forum and a Discord channel provide rapid feedback. The project follows semantic versioning, ensuring backward compatibility of the API surface.

Use Cases

1. Personal Cloud – Deploy a self‑hosted Nextcloud instance behind the HSHQ VPN, exposing it only to trusted devices.
2. Secure Email – Spin up Postfix/Postgrey with Authelia authentication, leveraging HSHQ’s internal TLS for inbound/outbound mail.
3. Family Network – Invite relatives’ HSHQ instances to form a mesh, sharing files and media via a single Caddy front‑end.
4. Developer Sandbox – Use the custom ISO builder to spin up a disposable environment for testing webhooks or OAuth flows.
5. Edge Computing – Run