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.
235 lines
6.2 KiB
Markdown
235 lines
6.2 KiB
Markdown
# 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
|
|
|
|
1. **Simplicity First**: Avoid overengineering
|
|
2. **Declarative Over Imperative**: Terraform, Docker Compose
|
|
3. **Infrastructure as Code**: Everything version-controlled
|
|
4. **Show Control**: Build things ourselves where it demonstrates skill
|
|
5. **Professional**: Production-grade practices
|