ee5e319dad
- Add ADR.md documenting all technology stack decisions with rationale - Create comprehensive ROADMAP.md with 10-phase implementation plan - Add 3 architecture diagrams (AWS infrastructure, application stack, network) - Document collaboration guidelines in `.github/copilot-instructions.md` - Technology stack descisions: AWS, Terraform, Ansible, Docker Compose, PostgreSQL Phase 1 establishes foundation for automated Gitea deployment with proper decision tracking and incremental development approach.
6.2 KiB
Architecture Decision Records (ADR)
This document tracks all significant architectural decisions made during the project, including rationale and trade-offs.
ADR-001: Cloud Provider - AWS
Date: 2026-06-08
Status: Accepted
Decision: Use Amazon Web Services (AWS)
Rationale:
- Industry-standard cloud provider with comprehensive service portfolio
- Access to managed services when beneficial
- Strong ecosystem and community support
- Terraform has excellent AWS provider support
ADR-002: Infrastructure as Code - Terraform
Date: 2026-06-08
Status: Accepted
Decision: Use Terraform for infrastructure provisioning
Rationale:
- Declarative approach (aligns with project philosophy)
- Industry standard for cloud infrastructure
- Excellent AWS provider
- State management enables reproducibility
Scope: VPC, EC2, Security Groups, S3, Route 53
ADR-003: Configuration Management - Ansible
Date: 2026-06-08
Status: Accepted
Decision: Use Ansible for system configuration (kept minimal)
Rationale:
- Avoids problematic user-data scripts (bad experience with debugging)
- Idempotent - can re-run if setup fails
- Real-time output visibility via SSH
- Professional separation of concerns: Terraform (infra) → Ansible (config) → Docker (apps)
Scope: Install Docker, configure system basics, setup firewall Philosophy: Keep Ansible simple - no fancy roles or complexity
Alternative Considered: User-data scripts - rejected due to debugging difficulty and one-shot nature
ADR-004: Application Deployment - Docker + Docker Compose
Date: 2026-06-08
Status: Accepted
Decision: Use Docker with Docker Compose for application orchestration
Rationale:
- Fully declarative (docker-compose.yml)
- Easy to test locally (dev/prod parity)
- Simple version control and updates
- Gitea has official Docker images
- Portable and reproducible
Scope: Gitea, nginx, PostgreSQL, monitoring stack (later)
ADR-005: Database - Self-Hosted PostgreSQL in Docker
Date: 2026-06-08
Status: Accepted
Decision: PostgreSQL container, not RDS
Rationale:
- Simpler architecture (everything in docker-compose.yml)
- Shows ability to build and manage backups ourselves
- More control over configuration
- Cost-effective
- PostgreSQL is Gitea's recommended database
Trade-offs:
- Pros: Greater control, cost-effective, simpler architecture
- Cons: Requires custom backup automation and testing
Backup Strategy: Custom scripts with pg_dump to S3 (detailed in backup phase)
Future Consideration: For higher availability requirements or larger scale, RDS would provide managed backups, point-in-time recovery, and Multi-AZ deployment
ADR-006: Reverse Proxy - Nginx
Date: 2026-06-08
Status: Accepted
Decision: Nginx as reverse proxy
Rationale:
- Lightweight and performant
- Simple configuration for basic proxying
- Industry standard
- Works well in Docker
Scope: SSL termination, proxy to Gitea, HTTP→HTTPS redirect
ADR-007: SSL Certificates - Let's Encrypt
Date: 2026-06-08
Status: Accepted
Decision: Let's Encrypt with certbot
Rationale:
- Free, automated, trusted certificates
- Widely accepted by all browsers (no certificate warnings)
- Auto-renewal reduces operational burden
- Industry-standard solution for SSL/TLS
Requirement: Valid domain name pointing to server
ADR-008: Update Automation - Watchtower
Date: 2026-06-08
Status: Accepted
Decision: Watchtower for Docker image updates
Rationale:
- Purpose-built for Docker environments
- Simple to configure (runs as container)
- Automatic image updates on schedule
- Minimal complexity
Scope: Monitor and update Gitea, nginx, and other containers
ADR-009: Monitoring - Prometheus + Grafana
Date: 2026-06-08
Status: Accepted (implementation later)
Decision: Prometheus for metrics, Grafana for visualization
Rationale:
- Industry standard monitoring stack
- Powerful querying with PromQL
- Rich visualization and alerting capabilities
- Strong community and pre-built dashboards
Note: To be implemented in later phase
ADR-010: Logging - Loki + Promtail
Date: 2026-06-08
Status: Accepted (implementation later)
Decision: Loki for log aggregation, Promtail for collection
Rationale:
- Lightweight compared to ELK stack
- Integrates with Grafana (single pane of glass)
- Good fit for Docker environments
Note: To be implemented in later phase
ADR-011: Backup Strategy - Custom Scripts + S3
Date: 2026-06-08
Status: Accepted (implementation later)
Decision: Bash scripts with pg_dump and AWS S3
Rationale:
- Simple and maintainable
- Full control over backup process and scheduling
- S3 provides highly durable storage (99.999999999%)
- Easy to test and validate restore procedures
Scope:
- Database backups (pg_dump)
- Gitea repository data
- Configuration files
- Automated scheduling with cron
Note: Details to be designed in backup phase
Technology Stack Summary
| Layer | Technology | Rationale |
|---|---|---|
| Cloud | AWS | Industry standard |
| Infrastructure | Terraform | Declarative IaC |
| Configuration | Ansible (minimal) | System setup, avoids user-data |
| Compute | EC2 | Flexible VM hosting |
| Application | Docker Compose | Declarative orchestration |
| Database | PostgreSQL (Docker) | Self-managed, shows control |
| Reverse Proxy | Nginx | Lightweight, standard |
| SSL | Let's Encrypt | Free, automated, professional |
| DNS | Route 53 | AWS-native |
| Updates | Watchtower | Docker-native automation |
| Backups | Scripts + S3 | Custom, controlled |
| Monitoring | Prometheus + Grafana | Industry standard |
| Logging | Loki + Promtail | Lightweight, integrated |
Core Principles
- Simplicity First: Avoid overengineering
- Declarative Over Imperative: Terraform, Docker Compose
- Infrastructure as Code: Everything version-controlled
- Show Control: Build things ourselves where it demonstrates skill
- Professional: Production-grade practices