add comprehensive documentation for all Ansible roles
- Add main README with infrastructure overview and usage instructions - Document bootstrap role for server initialization and security hardening - Document common role for shared server configuration - Document cron role for scheduled tasks and automation - Document docker role with detailed service descriptions and deployment patterns - Include MMDL service documentation with setup requirements - Add troubleshooting guides and security considerations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
131
README.md
Normal file
131
README.md
Normal file
@ -0,0 +1,131 @@
|
||||
# Personal Infrastructure Ansible Playbook
|
||||
|
||||
This Ansible playbook automates the setup and management of a personal self-hosted infrastructure running Docker containers for various services.
|
||||
|
||||
## Overview
|
||||
|
||||
The playbook manages two main environments:
|
||||
- **Bootstrap server** (`netcup`): Initial server setup with Tailscale VPN
|
||||
- **Docker server** (`docker-01`): Main application server running containerized services
|
||||
|
||||
## Services Deployed
|
||||
|
||||
The Docker role deploys and manages the following self-hosted services:
|
||||
|
||||
- **Authentication**: Authentik (SSO/Identity Provider)
|
||||
- **Media**: Audiobookshelf, Calibre, Pinchflat
|
||||
- **Productivity**: Ghost blog, Gitea, Code Server, Grist, TasksMD, Stirling PDF, MMDL (Task Management)
|
||||
- **Communication**: GoToSocial, Matrix (Conduit)
|
||||
- **File Management**: Hoarder, Paperless-NGX, Syncthing, Manyfold
|
||||
- **Monitoring**: Changedetection, Glance dashboard, Dawarich location tracking
|
||||
- **Utilities**: Baikal (CalDAV/CardDAV), HeyForm, Pingvin Share, Pinry
|
||||
- **Notifications**: Apprise API
|
||||
- **Reverse Proxy**: Caddy
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
├── site.yml # Main playbook
|
||||
├── bootstrap.yml # Server bootstrap playbook
|
||||
├── dns.yml # AWS Route53 DNS management
|
||||
├── hosts.yml # Inventory file
|
||||
├── requirements.yml # External role dependencies
|
||||
└── roles/
|
||||
├── bootstrap/ # Initial server setup
|
||||
├── common/ # Common server configuration
|
||||
├── cron/ # Scheduled tasks
|
||||
└── docker/ # Docker services deployment
|
||||
```
|
||||
|
||||
## Roles Documentation
|
||||
|
||||
Each role has detailed documentation in its respective directory:
|
||||
|
||||
### [Bootstrap Role](roles/bootstrap/README.md)
|
||||
Performs initial server setup and hardening:
|
||||
- Creates user accounts with SSH key authentication
|
||||
- Configures passwordless sudo and security hardening
|
||||
- Installs essential packages and configures UFW firewall
|
||||
- Sets up Tailscale VPN for secure network access
|
||||
|
||||
### [Common Role](roles/common/README.md)
|
||||
Provides shared configuration for all servers:
|
||||
- Installs common packages (aptitude)
|
||||
- Enables UFW firewall with default deny policy
|
||||
- Ensures consistent base configuration across infrastructure
|
||||
|
||||
### [Cron Role](roles/cron/README.md)
|
||||
Manages scheduled tasks and automation:
|
||||
- **Warhammer RSS Feed Updater**: Daily job that generates and updates RSS feeds
|
||||
- Integrates with Docker services for content generation
|
||||
- Supports easy addition of new scheduled tasks
|
||||
|
||||
### [Docker Role](roles/docker/README.md)
|
||||
The most comprehensive role, deploying 25+ containerized services:
|
||||
- **Core Infrastructure**: Caddy reverse proxy, Authentik SSO, Dockge management
|
||||
- **Development Tools**: Gitea, Code Server, Matrix communication
|
||||
- **Media Management**: Audiobookshelf, Calibre, Ghost blog
|
||||
- **Productivity**: Paperless-NGX, Baikal calendar, Glance dashboard
|
||||
- **Security Features**: Centralized authentication, network isolation, container hardening
|
||||
- **Monitoring**: Comprehensive service health monitoring and alerting
|
||||
|
||||
## Usage
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Install Ansible and required collections:
|
||||
```bash
|
||||
ansible-galaxy install -r requirements.yml
|
||||
```
|
||||
|
||||
2. Configure your inventory in `hosts.yml` with your server details
|
||||
|
||||
### Bootstrap a New Server
|
||||
|
||||
```bash
|
||||
ansible-playbook bootstrap.yml -i hosts.yml
|
||||
```
|
||||
|
||||
This will:
|
||||
- Create a user account
|
||||
- Install and configure Tailscale VPN
|
||||
- Set up basic security
|
||||
|
||||
### Deploy Docker Services
|
||||
|
||||
```bash
|
||||
ansible-playbook site.yml -i hosts.yml
|
||||
```
|
||||
|
||||
Or deploy specific services using tags:
|
||||
```bash
|
||||
# Deploy only Caddy reverse proxy
|
||||
ansible-playbook site.yml -i hosts.yml --tags caddy
|
||||
|
||||
# Deploy authentication services
|
||||
ansible-playbook site.yml -i hosts.yml --tags authentik
|
||||
|
||||
# Deploy task management
|
||||
ansible-playbook site.yml -i hosts.yml --tags mmdl
|
||||
```
|
||||
|
||||
### Manage DNS Records
|
||||
|
||||
```bash
|
||||
ansible-playbook dns.yml -i hosts.yml
|
||||
```
|
||||
|
||||
Updates AWS Route53 DNS records for configured domains (`thesatelliteoflove.com` and `nerder.land`).
|
||||
|
||||
## Configuration
|
||||
|
||||
- Service configurations are templated in `roles/docker/templates/`
|
||||
- Environment variables and secrets should be managed through Ansible Vault
|
||||
- Docker Compose files are generated from Jinja2 templates
|
||||
|
||||
## Security Notes
|
||||
|
||||
- Uses Tailscale for secure network access
|
||||
- Caddy provides automatic HTTPS with Let's Encrypt
|
||||
- Services are containerized for isolation
|
||||
- UFW firewall rules are managed via Docker integration
|
Reference in New Issue
Block a user