🚀 Quick Start • 📁 Structure • 🔧 Development • 📚 Documentation
This infrastructure monorepo contains the complete platform-as-code for All Things Linux, a 501(c)(3) non-profit organization. We manage infrastructure for 10,000+ community members using modern GitOps practices and infrastructure-as-code principles.
Infrastructure Only - Applications live in separate repositories:
- 🏗️ Infrastructure Provisioning - Terraform for Hetzner Cloud resources
- ⚙️ Configuration Management - Ansible for server configuration
- 🔍 Monitoring & Observability - Prometheus, Grafana, and alerting
- 🌐 Network & Security - Load balancing, SSL, firewalls
- 📦 Platform Services - Shared services (databases, caching, etc.)
Applications deploy to this infrastructure but live independently:
- Discord Bot (Tux) - Community automation and moderation
- ATL Wiki - Educational resources and documentation
- ATL Tools - Self-hosted applications suite
- ATL Chat - Multi-platform communication bridging
- ATL Dev - Developer pubnix and hosting platform
The atl
CLI provides a unified interface for all infrastructure operations:
# Install dependencies
uv sync
# Quick operations
atl plan # Plan infrastructure changes
atl apply -y # Apply changes with auto-approve
atl lint --fix # Run linting with auto-fix
atl docs build --serve # Build and serve documentation
# Organized commands
atl infra plan # Infrastructure planning
atl infra apply # Infrastructure deployment
atl infra destroy # Infrastructure destruction
atl quality lint # Code quality checks
atl docs build # Documentation generation
atl utils update-collections # Ansible collections update
# Get help
atl info # Show available commands
atl status # Check tool availability
atl <command> --help # Detailed help for any command
- Python 3.11+ with uv for dependency management
- Terraform for infrastructure provisioning
- Ansible for configuration management
- Hetzner Cloud account and API token
- Cloudflare account and API token
-
Clone and setup:
git clone <repository-url> cd infra # Install dependencies uv sync uv run ansible-galaxy collection install -r ansible/collections/requirements.yml
-
Configure secrets:
# Copy secrets template cp configs/secrets.example.yml configs/secrets.yml # Edit with your actual credentials (never commit this!) edit configs/secrets.yml
-
Set up development environment:
# Install pre-commit hooks ./scripts/setup/setup-hooks.sh # Run validation atl lint
-
Deploy infrastructure:
# Plan changes first cd terraform/environments/staging terraform plan # Apply infrastructure terraform apply # Configure servers cd ../../../ansible ansible-playbook -i inventories/dynamic.py playbooks/site.yml
infra/ # 🏗️ Infrastructure Monorepo
├── 📋 README.md # This file
├── 🔧 configs/ # 🎯 Configuration Management
│ ├── domains.yml # Domain configurations
│ ├── environments.yml # Environment definitions
│ └── secrets.example.yml # Secrets template (never commit secrets.yml!)
│
├── 🏗️ terraform/ # Infrastructure Provisioning
│ ├── modules/ # Reusable Terraform modules
│ │ ├── network/ # VPC, subnets, security groups
│ │ ├── compute/ # Servers, load balancers
│ │ └── security/ # SSL, firewalls, monitoring
│ ├── environments/ # Environment-specific configs
│ │ ├── production/ # Production infrastructure
│ │ ├── staging/ # Staging environment
│ │ └── development/ # Development environment
│ └── shared/ # Cross-environment resources (DNS, etc.)
│
├── ⚙️ ansible/ # Configuration Management
│ ├── ansible.cfg # Ansible configuration
│ ├── inventories/ # Dynamic and static inventories
│ │ └── dynamic.py # Dynamic inventory from Terraform
│ ├── playbooks/ # Ansible playbooks
│ │ ├── site.yml # Main deployment playbook
│ │ ├── infrastructure/ # Infrastructure setup playbooks
│ │ ├── security/ # Security hardening
│ │ └── domains/ # Domain-specific deployments
│ ├── roles/ # Reusable Ansible roles
│ │ ├── system/ # Base system configuration
│ │ ├── docker/ # Docker and containers
│ │ └── monitoring/ # Monitoring agents
│ ├── group_vars/ # Group variables
│ ├── host_vars/ # Host-specific variables
│ └── collections/ # Ansible collections requirements
│
├── 📊 monitoring/ # Observability Stack
│ ├── prometheus/ # Metrics collection
│ ├── grafana/ # Dashboards and visualization
│ └── alerting/ # Alert rules and notifications
│
├── 🔧 scripts/ # Automation and Tooling
│ ├── deploy.py # Modern Python deployment CLI
│ ├── lint.py # Code quality and validation
│ ├── docs.py # Documentation generation
│ ├── common/ # Shared utilities
│ └── setup/ # Environment setup scripts
│
├── 📚 docs/ # Infrastructure Documentation
│ ├── guides/ # How-to guides
│ ├── architecture/ # Architecture decisions
│ ├── runbooks/ # Operational procedures
│ └── setup/ # Setup and configuration
│
├── 🔄 .github/workflows/ # CI/CD Pipelines
│ ├── terraform.yml # Infrastructure validation
│ ├── ansible.yml # Configuration validation
│ └── docs.yml # Documentation deployment
│
└── 🐍 Python Environment # Development Environment
├── pyproject.toml # uv dependencies & CLI tools
├── uv.lock # Locked dependencies
└── .python-version # Python version file
This monorepo follows modern platform engineering patterns:
- 🔄 GitOps - Infrastructure changes via git workflows
- 📦 Modular - Reusable Terraform modules and Ansible roles
- 🌍 Multi-environment - Consistent dev/staging/production
- 🔍 Observable - Built-in monitoring and alerting
- 🔒 Secure - Security hardening and secrets management
- 📱 App-agnostic - Applications deploy independently
A single, powerful CLI that consolidates all infrastructure operations into an intuitive interface:
The atl
CLI provides a single interface for all infrastructure operations:
Command Group | Purpose | Key Features |
---|---|---|
atl infra |
Infrastructure management | Terraform + Ansible deployment with rich output |
atl quality |
Code quality validation | Multi-format linting, auto-fix capabilities |
atl docs |
Documentation generation | Automated docs from infrastructure code |
atl utils |
Utility operations | Collection updates, maintenance tasks |
# Quick access commands
atl plan # Preview infrastructure changes
atl apply # Apply infrastructure changes
atl lint # Run validation checks
# Organized commands
atl infra plan --environment staging
atl infra apply --environment production
atl quality lint --fix # Auto-fix common issues
atl docs build --serve # Generate and serve documentation
# Get help and status
atl info # Show all available commands
atl status # Check tool availability
Comprehensive team access management:
- 🔧 Platform Engineering: Full infrastructure access
- ☁️ Cloud Operations: Environment management and monitoring
- 🔒 Security: Security policies and compliance
- 📊 Site Reliability: Monitoring and incident response
- 🖥️ Backend Engineers: API and service deployment
- 🎨 Frontend Engineers: Web application deployment
- 🐍 Python Developers: Discord bot and tools deployment
- 📱 Mobile Developers: Mobile app infrastructure
- 👨💼 Management: Oversight and resource allocation
- 🛡️ Moderation: Community management tools
- 🎨 Creative: Content and brand management
Environment | Purpose | Infrastructure |
---|---|---|
Production | Live services | High-availability, monitoring, backups |
Staging | Pre-production testing | Production-like, automated testing |
Development | Feature development | Lightweight, rapid iteration |
- 🌐 Load Balancing: HAProxy with automatic failover
- 🗄️ Databases: PostgreSQL clusters with Redis caching
- 📊 Monitoring: Prometheus + Grafana + AlertManager
- 🔍 Logging: Centralized log aggregation and analysis
- 🔒 Security: Automated security scanning and hardening
- 💾 Backups: Automated backup and disaster recovery
# Install development dependencies
uv sync
# Set up lefthook (pre-commit) hooks
./scripts/setup/setup-hooks.sh
# Validate your setup
atl lint
- 🌿 Branch: Create feature branch from
main
- 💻 Develop: Make infrastructure changes
- ✅ Validate: Run
atl lint
- 🧪 Test: Deploy to development environment
- 📝 Document: Update relevant documentation
- 🔄 PR: Create pull request for review
- 🚀 Deploy: Merge triggers deployment pipeline
# Syntax validation
atl lint
# Infrastructure planning
cd terraform/environments/development
terraform plan
# Configuration testing
cd ansible
ansible-playbook --syntax-check playbooks/site.yml
Comprehensive documentation available in docs/
:
- 📋 Setup Guide - Installation and configuration
- 🏗️ Architecture - System design and decisions
- 📖 Runbooks - Operational procedures
- 🔧 Development - Development workflow
- 📖 Read the development guide
- 🍴 Fork this repository
- 🌿 Create a feature branch
- ✅ Test your changes thoroughly
- 📝 Document any new features
- 🔄 Submit a pull request
This infrastructure code is licensed under the MIT License. See LICENSE for details.
All Things Linux • A 501(c)(3) Non-Profit Organization
Empowering the Linux ecosystem through education, collaboration, and open infrastructure
For local development and testing of Ansible roles, please refer to the Local Development Environment Guide.
Warning: The following commands will provision and modify live production infrastructure.
-
Initialize Terraform:
cd terraform/environments/production terraform init
-
Apply Terraform Plan:
terraform apply
-
Run Ansible Playbook: Once infrastructure is provisioned, apply the configuration with Ansible:
ansible-playbook -i inventories/production site.yml
Please see CONTRIBUTING.md
for details on how to contribute to this project.