Deploying xsrv

Introduction

xsrv is a comprehensive server administration toolkit built on Ansible, providing production-ready playbooks and roles for deploying self-hosted services. Rather than configuring each service manually, xsrv offers a declarative approach where you define your desired server state and let Ansible handle the implementation.

The toolkit includes dozens of pre-configured roles for popular self-hosted applications, from media servers and file sharing to monitoring and backup solutions. Each role follows security best practices and integrates seamlessly with others in the collection.

Key highlights of xsrv:

• Ansible-Based: Declarative infrastructure as code using Ansible playbooks
• Pre-Built Roles: 50+ roles for common self-hosted applications
• Security First: Roles include hardening, firewall rules, and secure defaults
• Documentation: Each role includes comprehensive documentation and examples
• Modular Design: Pick and choose only the services you need
• Easy Updates: Update all services with a single command
• Backup Integration: Built-in backup roles for data protection
• Monitoring Ready: Includes monitoring and alerting configurations
• Active Development: Regular updates and community contributions
• Open Source: Licensed under GPL-3.0

This guide walks through deploying xsrv on Klutch.sh using Docker, where you can run the Ansible controller or deploy xsrv-managed applications.

Why Deploy xsrv on Klutch.sh

Deploying xsrv on Klutch.sh provides several advantages for managing your infrastructure:

Centralized Management: Run your Ansible controller on Klutch.sh to manage servers across multiple environments from a single location.

Persistent Configuration: Store your Ansible inventories, playbooks, and vault files in persistent volumes that survive redeployments.

HTTPS by Default: Access any xsrv-managed web applications through Klutch.sh’s automatic SSL certificates.

GitHub Integration: Version control your infrastructure configurations in GitHub with automatic deployment on push.

Scalable Resources: Allocate resources based on the number of managed hosts and playbook complexity.

Environment Variable Management: Securely store Ansible vault passwords and SSH keys through Klutch.sh’s environment variable system.

Custom Domains: Assign custom domains to any web-facing services deployed through xsrv roles.

Always-On Availability: Your infrastructure management platform remains accessible around the clock.

Prerequisites

Before deploying xsrv on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your xsrv configuration
• Basic familiarity with Ansible concepts (playbooks, roles, inventory)
• SSH access to target servers you want to manage
• Understanding of Linux server administration

Understanding xsrv Architecture

xsrv operates as a collection of Ansible roles organized into a cohesive toolkit:

Ansible Controller: The machine running Ansible commands, which connects to and configures target hosts.

Roles: Pre-built configurations for specific applications (e.g., Nextcloud, Gitea, monitoring).

Playbooks: YAML files defining which roles apply to which hosts.

Inventory: Definition of your managed hosts and their groupings.

Vault: Encrypted storage for sensitive variables like passwords and API keys.

Available Role Categories

xsrv includes roles across multiple categories:

Category	Example Roles
File Sharing	Nextcloud, Samba, Syncthing
Media	Jellyfin, Transmission, Icecast
Monitoring	Netdata, Grafana, Prometheus
Development	Gitea, GitLab Runner, Jenkins
Communication	Matrix, Mumble, Jitsi
Backup	Borgbackup, Rsnapshot
Security	Fail2ban, ClamAV, Lynis
System	Docker, Common, Firewall

Preparing Your Repository

To deploy xsrv on Klutch.sh, create a GitHub repository for your infrastructure configuration.

Repository Structure

xsrv-infrastructure/
├── Dockerfile
├── ansible.cfg
├── inventory/
│   ├── hosts.yml
│   └── group_vars/
│       └── all.yml
├── playbooks/
│   └── main.yml
├── requirements.yml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for the Ansible controller:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    openssh-client \
    git \
    sshpass \
    && rm -rf /var/lib/apt/lists/*

# Install Ansible and dependencies
RUN pip install --no-cache-dir \
    ansible \
    ansible-lint \
    jmespath \
    netaddr

# Create working directory
WORKDIR /ansible

# Copy configuration files
COPY ansible.cfg /ansible/
COPY inventory/ /ansible/inventory/
COPY playbooks/ /ansible/playbooks/
COPY requirements.yml /ansible/

# Install xsrv collection
RUN ansible-galaxy collection install nodiscc.xsrv

# Set environment variables
ENV ANSIBLE_HOST_KEY_CHECKING=False
ENV ANSIBLE_INVENTORY=/ansible/inventory/hosts.yml

# Default command
CMD ["ansible-playbook", "--version"]

Ansible Configuration

Create an ansible.cfg file:

[defaults]
inventory = inventory/hosts.yml
roles_path = ~/.ansible/roles
collections_paths = ~/.ansible/collections
host_key_checking = False
retry_files_enabled = False
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400

[privilege_escalation]
become = True
become_method = sudo
become_user = root

[ssh_connection]
pipelining = True
ssh_args = -o ControlMaster=auto -o ControlPersist=60s

Inventory Configuration

Create inventory/hosts.yml:

all:
  hosts:
    webserver:
      ansible_host: "{{ lookup('env', 'WEBSERVER_HOST') }}"
      ansible_user: "{{ lookup('env', 'ANSIBLE_USER') }}"
      ansible_ssh_private_key_file: /ansible/ssh/id_rsa
  vars:
    ansible_python_interpreter: /usr/bin/python3

Requirements File

Create requirements.yml to install the xsrv collection:

collections:
  - name: nodiscc.xsrv
    version: ">=1.0.0"

Sample Playbook

Create playbooks/main.yml:

---
- name: Configure web server with xsrv roles
  hosts: webserver
  become: yes
  collections:
    - nodiscc.xsrv

  roles:
    - role: nodiscc.xsrv.common
    - role: nodiscc.xsrv.monitoring
    - role: nodiscc.xsrv.backup

Environment Variables Reference

Variable	Required	Default	Description
WEBSERVER_HOST	Yes	-	Target server IP or hostname
ANSIBLE_USER	Yes	-	SSH user for target servers
ANSIBLE_VAULT_PASSWORD	No	-	Password for encrypted vault files
SSH_PRIVATE_KEY	Yes	-	Base64-encoded SSH private key

Deploying xsrv on Klutch.sh

Follow these steps to deploy your xsrv Ansible controller:

Prepare SSH Keys

Generate or gather SSH keys for accessing your target servers:

1. Create a dedicated key pair for Ansible management
2. Add the public key to authorized_keys on target servers
3. Base64-encode the private key for secure storage

Create Your Configuration Repository

Set up your xsrv configuration repository with inventory and playbooks defining your infrastructure.

Push to GitHub

Initialize and push your repository:

git init
git add .
git commit -m "Initial xsrv infrastructure configuration"
git remote add origin https://github.com/yourusername/xsrv-infrastructure.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Name it “xsrv-controller” or similar.

Create a New App

Within your project, create a new app and connect your GitHub repository containing the xsrv configuration.

Configure the Deployment

Since this is a management tool rather than a web service, you may want to configure it as a worker or scheduled task depending on your needs.

For web-based interfaces or API access:

• Select HTTP as the traffic type
• Set the internal port as needed

Set Environment Variables

Configure the following environment variables:

Variable	Value
WEBSERVER_HOST	IP or hostname of your target server
ANSIBLE_USER	SSH username for target servers
SSH_PRIVATE_KEY	Base64-encoded SSH private key
ANSIBLE_VAULT_PASSWORD	Your vault password (if using encrypted vars)

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/ansible/ssh	100 MB	SSH keys and known hosts
/ansible/logs	1 GB	Ansible execution logs
/ansible/facts	500 MB	Cached facts for faster runs

Deploy Your Application

Click Deploy to build and start your xsrv controller. Klutch.sh will:

• Build the Docker image with Ansible and xsrv
• Install the xsrv collection
• Configure the environment
• Start the container

Run Your Playbooks

Access your container to run Ansible playbooks against your infrastructure.

Using xsrv Roles

Common Role

The common role provides baseline server configuration:

- role: nodiscc.xsrv.common
  vars:
    common_hostname: "webserver"
    common_timezone: "America/New_York"
    common_dns_servers:
      - 1.1.1.1
      - 8.8.8.8

Monitoring Role

Set up comprehensive monitoring:

- role: nodiscc.xsrv.monitoring_netdata
  vars:
    netdata_streaming_enabled: yes
    netdata_streaming_destination: "monitor.example.com:19999"

Backup Role

Configure automated backups:

- role: nodiscc.xsrv.backup
  vars:
    backup_repository: "/backup/borg"
    backup_passphrase: "{{ vault_backup_passphrase }}"
    backup_schedule: "daily"

Production Best Practices

Security Recommendations

• Vault Encryption: Always encrypt sensitive variables with Ansible Vault
• Key Management: Rotate SSH keys regularly and use per-environment keys
• Least Privilege: Use minimal permissions on target servers
• Audit Logging: Enable comprehensive logging of Ansible runs
• Role Pinning: Pin xsrv collection versions in production

Workflow Recommendations

• Version Control: Keep all configurations in Git
• Testing: Test playbook changes in staging before production
• Documentation: Document custom configurations and overrides
• Incremental Changes: Apply changes incrementally rather than all at once

Backup Strategy

• Configuration Backup: Version control is your configuration backup
• Vault Backup: Securely store vault password separately
• Key Backup: Maintain encrypted backups of SSH keys
• State Backup: Back up target server data using xsrv backup roles

Troubleshooting Common Issues

SSH Connection Failures

Symptoms: Ansible cannot connect to target hosts.

Solutions:

• Verify SSH key is correctly mounted and has proper permissions
• Confirm target host is accessible from Klutch.sh network
• Check username and hostname in inventory
• Review SSH connection settings in ansible.cfg

Role Application Failures

Symptoms: Playbook runs fail during role execution.

Solutions:

• Check role requirements and dependencies
• Verify target system meets role prerequisites
• Review role variables for required settings
• Consult role documentation for troubleshooting

Vault Decryption Issues

Symptoms: Ansible cannot decrypt vault-encrypted variables.

Solutions:

• Verify ANSIBLE_VAULT_PASSWORD environment variable
• Confirm vault password is correct
• Check vault file format and encryption

Additional Resources

• xsrv Documentation
• xsrv GitHub Repository
• xsrv on Ansible Galaxy
• Ansible Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying xsrv on Klutch.sh provides a centralized, always-available Ansible controller for managing your self-hosted infrastructure. The combination of xsrv’s comprehensive role library and Klutch.sh’s deployment simplicity means you can manage complex server configurations with confidence.

Whether you’re setting up a single server or orchestrating a multi-node deployment, xsrv’s battle-tested Ansible roles handle the complexity while you focus on defining your desired infrastructure state.