xsrv

xsrv is a modular, Ansible‑driven framework designed to provision and maintain a full stack of self‑hosted services on one or more Debian‑based servers. At its core, it abstracts common infrastructure patterns—web serving, reverse proxying, authentication, logging, and storage—into reusable Ansible roles. Each role encapsulates a complete deployment of a popular open‑source application (e.g., Nextcloud, Matrix, Jitsi, Podman), allowing developers to compose a custom stack by simply enabling the desired roles in an inventory file. The optional command‑line tool exposes a curated set of actions (e.g., xsrv deploy, xsrv backup) that wrap the underlying Ansible playbooks, streamlining routine operations such as rolling updates or configuration changes.

Technical Stack

• Language & Runtime: The primary orchestrator is Ansible (YAML playbooks), with optional Python scripts for the CLI wrapper. Roles are written in Ansible’s declarative syntax, leveraging Jinja2 templates for dynamic configuration.
• Operating System: Debian (stretch/jessie) or derivatives, ensuring broad compatibility with the package repositories used by most roles.
• Container Engine: podman is provided as a role, offering OCI‑compatible container management without requiring Docker. This facilitates lightweight isolation for services like ollama or transmission.
• Database & Persistence: Roles include PostgreSQL and MariaDB setups, while file‑based services use local storage or NFS mounts. The backup role implements rsnapshot for incremental snapshots.
• Networking: dnsmasq, apache (with PHP‑FPM), and nginx can be combined to form a reverse proxy layer. The framework also supports Caddy‑like automatic TLS via Let’s Encrypt integration in selected roles.

Core Capabilities

• Automated Provisioning: Idempotent playbooks that install, configure, and start services with minimal manual intervention.
• Service Orchestration: Each role exposes variables for fine‑grained tuning (e.g., nextcloud_admin_email, matrix_synapse_homeserver_name) and supports dependency ordering via Ansible’s dependencies feature.
• Monitoring & Logging: Integrated Graylog and GoAccess roles provide real‑time log aggregation, while monitoring_rsyslog forwards logs to centralized collectors.
• CI/CD Integration: The gitea_act_runner role allows GitHub‑style Actions to run on the same host, enabling a self‑contained DevOps pipeline.
• Extensibility: Roles are open source and can be forked or extended. Developers can add custom modules, modify templates, or create new roles that fit their niche services.

Deployment & Infrastructure

• Self‑Hosting Requirements: A single Debian server (or a cluster) with network access, sufficient disk space for media or backups, and a public DNS record if external access is needed.
• Scalability: The architecture supports horizontal scaling by adding more hosts to the Ansible inventory. Services that benefit from clustering (e.g., Nextcloud, Matrix Synapse) can be configured via role variables.
• Containerization: The podman role enables deployment of services as containers, reducing dependency conflicts and simplifying upgrades. Containers can be managed through Ansible’s podman_container module.
• High Availability: While not a built‑in HA solution, the framework can be combined with external tools (e.g., Keepalived, Pacemaker) to orchestrate failover for critical services.

Integration & Extensibility

• Plugin System: Roles can include custom Ansible modules or external scripts. For example, the matrix role ships with a lightweight Python webhook that triggers room creation on demand.
• Webhooks & APIs: Several services expose RESTful endpoints (e.g., Gitea, Nextcloud). The CLI can invoke these APIs to perform actions such as creating repositories or users.
• Customization: All configuration files are templated; developers can override defaults by adding variables in group or host vars. The readme_gen role even auto‑generates documentation from the inventory, ensuring that deployment details stay in sync.

Developer Experience

• Documentation: Comprehensive README files per role, hosted on ReadTheDocs, and a central usage guide. Inline comments in playbooks aid onboarding.
• Community Support: The project follows best practices guidelines, has an active CI pipeline, and welcomes contributions via GitLab merge requests. Issues are triaged quickly, and role maintainers provide assistance for custom deployments.
• Configuration Simplicity: The CLI abstracts complex Ansible commands, allowing developers to run xsrv deploy and let the framework resolve dependencies. Advanced users can drop into Ansible directly for deeper customization.

Use Cases

1. Personal Cloud Stack – Spin up a secure, self‑hosted environment with Nextcloud, Mail Dovecot, and Matrix for personal data, communication, and backup.
2. DevOps Sandbox – Deploy Gitea, Podman, and GitHub Actions runners on a single machine to experiment with CI/CD pipelines without external services.
3. Media & Streaming Hub – Combine Jellyfin, Owncast, and Mumble to create a home media center with live streaming and low‑