SelfHostBlocks

SelfHostBlocks is a NixOS‑centric platform that turns a bare server into a fully managed, privacy‑first groupware stack. At its core it bundles a curated set of NixOS modules—mail, calendar, file storage, authentication, and web services—into a single declarative configuration. Developers can drop the repository into any NixOS host, enable the selfhostblocks module, and immediately obtain a secure, self‑contained environment that automatically pulls the latest upstream packages. The system is designed to be opinionated yet extensible: every service follows the same configuration schema, so adding a new application or swapping an existing one only requires tweaking a small number of attributes.

Technical Stack & Architecture

• Language & Build System: The entire stack is written in Nix expression language and built by the Nix package manager. The selfhostblocks module is a collection of NixOS modules that import and configure services from the nixpkgs repository.
• Services: Includes Postfix/Dovecot for mail, Nextcloud/Seafile for file storage, CalDAV/CardDAV servers, and a reverse‑proxy layer (Caddy/Traefik) that exposes all services over HTTPS. Authentication is handled by OAuth2 and SAML providers that can be wired to LDAP or Keycloak.
• Database: PostgreSQL is the default relational backend, while Redis and Memcached are optional for caching and session storage. All database services are wrapped in Nix modules, ensuring consistent configuration across deployments.
• Networking: The platform relies on NixOS networking modules and the networking.firewall configuration. TLS certificates are managed by acme.sh or Let’s Encrypt, automatically rotated through the NixOS configuration.

Core Capabilities & APIs

• Declarative Configuration: Every service is exposed through a unified NixOS option set (services.selfhostblocks.<service>) that can be overridden per host. This eliminates the need for ad‑hoc shell scripts or manual edits.
• RESTful APIs: Services such as Nextcloud expose their native REST endpoints; SelfHostBlocks adds a thin proxy layer that injects authentication headers and rate‑limiting rules. Developers can also expose custom APIs by adding a services.selfhostblocks.webapp module.
• Webhooks & Event Hooks: The platform ships with a generic webhook dispatcher that can trigger external scripts on events like user creation, file upload, or mail receipt. This is useful for integrating CI/CD pipelines or custom notification services.
• Contract System: A novel feature that defines contracts—structured interfaces for modules. Contracts allow a module to declare the services it consumes and provides, enabling automated dependency resolution and tighter integration between components.

Deployment & Infrastructure

SelfHostBlocks is designed for bare-metal or virtualized environments running NixOS. Because the entire stack is built from source, it can be deployed on any hardware that supports NixOS (x86_64, aarch64). Docker or Podman containers are not required; however, the platform can be wrapped in a single NixOS VM image for quick provisioning. For scaling, each service can be horizontally replicated behind a load balancer, and the configuration supports declarative clustering for PostgreSQL (via Patroni) and Redis Sentinel. The use of Nix ensures reproducible builds, making it straightforward to roll back or upgrade services without downtime.

Integration & Extensibility

• Plugin System: Developers can add new services by writing a Nix module that follows the existing contract conventions. The repository contains a modules/ directory where each plugin can be imported and enabled in the host configuration.
• Custom Webhooks & Scripts: The services.selfhostblocks.webhook module allows arbitrary shell scripts to be executed in response to system events, giving developers fine‑grained control over automation.
• Third‑Party APIs: Existing services expose their own APIs (e.g., Nextcloud’s WebDAV, Postfix’s SMTP), so developers can integrate with external tools or build custom dashboards without modifying the core stack.
• Community Contributions: The project encourages pull requests that upstream to nixpkgs. Contributors can add new modules or improve existing ones, benefiting the wider Nix community.

Developer Experience

The documentation is organized into a comprehensive handbook that walks through module options, contract definitions, and deployment scenarios. A live demo pipeline (demo.yml) demonstrates a fully functional instance in minutes, which is invaluable for onboarding. Community support is facilitated through a Matrix channel and GitHub discussions, where developers can ask questions about module quirks or propose new features. The project’s continuous integration pipeline ensures that any change is automatically tested against a matrix of NixOS versions, giving confidence in stability.

Use Cases

• Privacy‑Focused Enterprises: Organizations that require full control over their data can deploy SelfHostBlocks to host email, file sharing, and calendar services without relying on external providers.
• Educational Institutions: Schools can provide students with a unified portal for documents, schedules, and communication while maintaining strict data sovereignty.
• Personal Developers: Hobbyists can spin up a personal server that offers Nextcloud, mail, and OAuth2 authentication with minimal configuration effort.
• DevOps Pipelines: The webhook system can be leveraged to trigger CI jobs or deploy containers when files are added to the storage layer.

Advantages Over Alternatives

• Unified Declarative Configuration: Unlike ad‑hoc setups, SelfHostBlocks offers a single source of