added ansible script
This commit is contained in:
liph
426
ansible/ARCHITECTURE.md
Normal file
426
ansible/ARCHITECTURE.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# Network Architecture
|
||||
|
||||
Visual overview of how all services connect and communicate.
|
||||
|
||||
## 🌐 Network Flow Diagram
|
||||
|
||||
```
|
||||
INTERNET
|
||||
│
|
||||
│ DNS A Records
|
||||
│ (cloud.yourdomain.com → SERVER_IP)
|
||||
↓
|
||||
┌───────────────┐
|
||||
│ Firewall (UFW)│
|
||||
│ Ports: 80 │
|
||||
│ 443 │
|
||||
│ 41641 │
|
||||
└───────┬───────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
│ │ │
|
||||
Port 80/443 Port 41641 Port 22
|
||||
│ │ │
|
||||
↓ ↓ ↓
|
||||
┌──────────────┐ ┌─────────────┐ ┌──────────┐
|
||||
│ CADDY │ │ TAILSCALE │ │ SSH │
|
||||
│ Reverse Proxy│ │ VPN │ │ Access │
|
||||
└──────┬───────┘ └─────┬───────┘ └──────────┘
|
||||
│ │
|
||||
│ │
|
||||
┌──────────┴────────┐ │
|
||||
│ │ │
|
||||
↓ ↓ ↓
|
||||
┌─────────┐ ┌─────────────────┐
|
||||
│ PUBLIC │ │ TAILSCALE-ONLY │
|
||||
│SERVICES │ │ SERVICES │
|
||||
└─────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Access Matrix
|
||||
|
||||
| Service | Public URL | Tailscale URL | Direct Access |
|
||||
|---------|-----------|---------------|---------------|
|
||||
| **Nextcloud** | ✅ https://cloud.domain.com | ✅ Via Tailscale IP | ❌ No |
|
||||
| **OnlyOffice** | ✅ https://office.domain.com | ✅ Via Tailscale IP | ❌ No |
|
||||
| **Excalidraw** | ✅ https://draw.domain.com | ✅ Via Tailscale IP | ❌ No |
|
||||
| **Obsidian** | ✅ https://notes.domain.com | ✅ Via Tailscale IP | ❌ No |
|
||||
| **Homarr** | ❌ 403 Forbidden | ✅ https://home.domain.com | ❌ No |
|
||||
| **Dockhand** | ❌ 403 Forbidden | ✅ https://manage.domain.com | ❌ No |
|
||||
| **Uptime Kuma** | ❌ 403 Forbidden | ✅ https://uptime.domain.com | ❌ No |
|
||||
| **PostgreSQL** | ❌ No | ❌ No | ✅ Docker network only |
|
||||
| **Redis** | ❌ No | ❌ No | ✅ Docker network only |
|
||||
| **Caddy** | ❌ No (serves others) | ❌ No | ✅ Docker network only |
|
||||
| **Watchtower** | ❌ No | ❌ No | ✅ Docker network only |
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Docker Network Topology
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────────────┐
|
||||
│ nextcloud_network (bridge) │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │PostgreSQL│ │ Redis │ │Nextcloud │ │OnlyOffice│ │
|
||||
│ │ :5432 │ │ :6379 │ │ :80 │ │ :80 │ │
|
||||
│ └──────────┘ └──────────┘ └────┬─────┘ └──────────┘ │
|
||||
│ ↑ ↑ │ │
|
||||
│ │ │ │ │
|
||||
│ └──────────────┴─────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────┐ ┌────┴─────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │Excalidraw│ │ Caddy │ │ Obsidian │ │ Homarr │ │
|
||||
│ │ :80 │ │80→:80 │ │ :3000 │ │ :7575 │ │
|
||||
│ └──────────┘ │443→:443 │ └──────────┘ └────┬─────┘ │
|
||||
│ │ │ │ │
|
||||
│ ┌──────────┐ │ │ ┌──────────┐ ↓ │
|
||||
│ │ Dockhand │ │ │ │ Uptime │ /var/run/ │
|
||||
│ │ :3000 │ │ │ │ Kuma │ docker.sock │
|
||||
│ └──────────┘ └──────────┘ │ :3001 │ (read-only) │
|
||||
│ └──────────┘ │
|
||||
│ ┌──────────────────────────────────────────────────┐ │
|
||||
│ │ Watchtower (monitors all) │ │
|
||||
│ │ Accesses: /var/run/docker.sock │ │
|
||||
│ └──────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└────────────────────────────────────────────────────────────────┘
|
||||
│ │
|
||||
│ Exposed Ports │ Internal
|
||||
│ │ Communication
|
||||
↓ ↓
|
||||
Host: 80, 443 Container-to-Container
|
||||
(Caddy only) via Docker DNS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Request Flow Examples
|
||||
|
||||
### Example 1: User Accesses Nextcloud
|
||||
|
||||
```
|
||||
User Browser
|
||||
│
|
||||
│ HTTPS GET https://cloud.yourdomain.com
|
||||
↓
|
||||
Internet
|
||||
│
|
||||
↓
|
||||
Firewall (Port 443)
|
||||
│
|
||||
↓
|
||||
Caddy Container (:443)
|
||||
│
|
||||
│ Validates SSL certificate
|
||||
│ Checks Caddyfile rules
|
||||
│ Proxies to backend
|
||||
↓
|
||||
Nextcloud Container (:80)
|
||||
│
|
||||
│ Checks trusted domains
|
||||
│ Queries PostgreSQL
|
||||
│ Checks Redis cache
|
||||
↓
|
||||
PostgreSQL + Redis
|
||||
│
|
||||
│ Returns data
|
||||
↓
|
||||
Nextcloud → Caddy → User
|
||||
```
|
||||
|
||||
### Example 2: User Accesses Homarr (via Tailscale)
|
||||
|
||||
```
|
||||
User Browser (on Tailscale)
|
||||
│
|
||||
│ HTTPS GET https://home.yourdomain.com
|
||||
↓
|
||||
Internet → DNS Resolution
|
||||
│
|
||||
↓
|
||||
Firewall (Port 443)
|
||||
│
|
||||
↓
|
||||
Caddy Container
|
||||
│
|
||||
│ Checks client IP: 100.64.x.x (Tailscale range)
|
||||
│ ✅ Match! Proxy to backend
|
||||
│
|
||||
↓
|
||||
Homarr Container (:7575)
|
||||
│
|
||||
│ Reads Docker socket
|
||||
│ Shows container status
|
||||
↓
|
||||
Returns dashboard → Caddy → User
|
||||
```
|
||||
|
||||
### Example 3: User Accesses Homarr (NOT on Tailscale)
|
||||
|
||||
```
|
||||
User Browser (public internet)
|
||||
│
|
||||
│ HTTPS GET https://home.yourdomain.com
|
||||
↓
|
||||
Internet → DNS Resolution
|
||||
│
|
||||
↓
|
||||
Firewall (Port 443)
|
||||
│
|
||||
↓
|
||||
Caddy Container
|
||||
│
|
||||
│ Checks client IP: NOT in 100.64.0.0/10
|
||||
│ ❌ No match! Return 403 Forbidden
|
||||
│
|
||||
↓
|
||||
403 Access Denied
|
||||
```
|
||||
|
||||
### Example 4: Nextcloud Connects to Database
|
||||
|
||||
```
|
||||
Nextcloud Container
|
||||
│
|
||||
│ Docker DNS lookup: next-db
|
||||
│ Resolves to: 172.20.0.x
|
||||
↓
|
||||
PostgreSQL Container (next-db:5432)
|
||||
│
|
||||
│ Internal Docker network
|
||||
│ No external exposure
|
||||
│
|
||||
↓
|
||||
Returns query results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Data Flow Diagram
|
||||
|
||||
### File Upload to Nextcloud
|
||||
|
||||
```
|
||||
User → Caddy → Nextcloud → Storage Volume
|
||||
│
|
||||
├→ PostgreSQL (metadata)
|
||||
└→ Redis (cache)
|
||||
```
|
||||
|
||||
### Document Editing with OnlyOffice
|
||||
|
||||
```
|
||||
User → Caddy → Nextcloud → Caddy → OnlyOffice
|
||||
│ │
|
||||
↓ ↓
|
||||
PostgreSQL Document
|
||||
(metadata) Processing
|
||||
│ │
|
||||
↓ ↓
|
||||
Nextcloud ←───────── OnlyOffice
|
||||
│
|
||||
↓
|
||||
Storage Volume
|
||||
```
|
||||
|
||||
### Watchtower Auto-Update
|
||||
|
||||
```
|
||||
Watchtower (cron: every 24h)
|
||||
│
|
||||
│ Check Docker Hub for new images
|
||||
↓
|
||||
New image available?
|
||||
│
|
||||
├─ NO → Sleep
|
||||
│
|
||||
├─ YES → Check container labels
|
||||
│
|
||||
├─ "enable=false" → Skip
|
||||
├─ "enable=true" → Pull & Update
|
||||
└─ "monitor-only=true" → Notify
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Boundaries
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ INTERNET (Untrusted) │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ UFW Firewall │ ← Layer 1: Host Firewall
|
||||
│ 22, 80, 443 │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ fail2ban │ ← Layer 2: Intrusion Detection
|
||||
│ SSH Protection │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ Caddy (HTTPS) │ ← Layer 3: TLS Termination
|
||||
│ SSL Validation │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────────────┼────────────────┐
|
||||
│ │ │
|
||||
┌───▼────┐ ┌────▼────┐ ┌─────▼─────┐
|
||||
│ Public │ │Tailscale│ │ Docker │ ← Layer 4: Network
|
||||
│Services│ │ Check │ │ Network │ Isolation
|
||||
└────────┘ └─────────┘ └───────────┘
|
||||
│
|
||||
┌────▼────┐
|
||||
│ Admin │ ← Layer 5: Admin Access
|
||||
│ Services│ (Tailscale VPN only)
|
||||
└─────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ Data Persistence
|
||||
|
||||
### Docker Volumes
|
||||
|
||||
```
|
||||
Host Filesystem
|
||||
│
|
||||
├── /var/lib/docker/volumes/
|
||||
│ ├── nextcloud_pg_data/ ← PostgreSQL database
|
||||
│ ├── nextcloud_redis_data/ ← Redis cache
|
||||
│ ├── nextcloud_nextcloud_data/ ← Nextcloud files
|
||||
│ ├── nextcloud_nextcloud_apps/ ← Nextcloud apps
|
||||
│ ├── nextcloud_onlyoffice_data/ ← OnlyOffice docs
|
||||
│ ├── nextcloud_caddy_data/ ← SSL certificates
|
||||
│ ├── nextcloud_caddy_config/ ← Caddy config
|
||||
│ ├── nextcloud_dockhand_data/ ← Dockhand settings
|
||||
│ └── nextcloud_uptime_kuma_data/ ← Uptime Kuma data
|
||||
│
|
||||
└── /opt/nextcloud-stack/
|
||||
├── configs/
|
||||
│ ├── caddy/Caddyfile
|
||||
│ └── nextcloud/
|
||||
├── data/
|
||||
│ ├── homarr/
|
||||
│ └── obsidian/
|
||||
└── backups/
|
||||
├── database/
|
||||
└── volumes/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Update Mechanism
|
||||
|
||||
### Watchtower Label-Based Control
|
||||
|
||||
```yaml
|
||||
# Auto-update allowed
|
||||
labels:
|
||||
- "com.centurylinklabs.watchtower.enable=true"
|
||||
→ Caddy, Excalidraw, Obsidian, Homarr, Dockhand, Uptime Kuma
|
||||
|
||||
# Monitor only (notify, no update)
|
||||
labels:
|
||||
- "com.centurylinklabs.watchtower.monitor-only=true"
|
||||
→ OnlyOffice
|
||||
|
||||
# Never auto-update (manual only)
|
||||
labels:
|
||||
- "com.centurylinklabs.watchtower.enable=false"
|
||||
→ Nextcloud, PostgreSQL, Redis
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📡 Monitoring Architecture
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ Uptime Kuma │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ HTTP Monitors (every 60s) │ │
|
||||
│ │ • https://cloud.yourdomain.com/status.php │ │
|
||||
│ │ • https://office.yourdomain.com/health │ │
|
||||
│ │ • https://draw.yourdomain.com │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ TCP Port Monitors │ │
|
||||
│ │ • next-db:5432 (PostgreSQL) │ │
|
||||
│ │ • next-redis:6379 (Redis) │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ SSL Certificate Monitor │ │
|
||||
│ │ • Expiry check (30-day warning) │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ Notifications │ │
|
||||
│ │ • Email alerts │ │
|
||||
│ │ • Slack/Discord webhooks (optional) │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
└────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Service Dependencies
|
||||
|
||||
```
|
||||
Nextcloud
|
||||
│
|
||||
├─ requires → PostgreSQL (healthy)
|
||||
├─ requires → Redis (healthy)
|
||||
└─ requires → Caddy (for external access)
|
||||
|
||||
OnlyOffice
|
||||
│
|
||||
└─ requires → Caddy (for external access)
|
||||
|
||||
Homarr, Dockhand
|
||||
│
|
||||
├─ requires → Docker Socket (read-only)
|
||||
└─ requires → Caddy (for Tailscale access)
|
||||
|
||||
Watchtower
|
||||
│
|
||||
└─ requires → Docker Socket (read-write)
|
||||
|
||||
All Services
|
||||
│
|
||||
└─ network → nextcloud_network
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Architecture Benefits
|
||||
|
||||
### High Availability Features
|
||||
- **Health checks**: Containers auto-restart on failure
|
||||
- **Database connection pooling**: Redis caching reduces DB load
|
||||
- **SSL auto-renewal**: Caddy handles certificate lifecycle
|
||||
|
||||
### Security Layers
|
||||
1. **Network**: UFW firewall + fail2ban
|
||||
2. **Transport**: TLS/SSL via Caddy
|
||||
3. **Access**: Tailscale VPN for admin interfaces
|
||||
4. **Secrets**: Ansible Vault encryption
|
||||
5. **Isolation**: Docker network segmentation
|
||||
|
||||
### Scalability Points
|
||||
- **Database**: Can migrate to external PostgreSQL
|
||||
- **Cache**: Redis can be scaled/clustered
|
||||
- **Storage**: Volumes can be moved to network storage
|
||||
- **Reverse Proxy**: Caddy can be load-balanced
|
||||
|
||||
---
|
||||
|
||||
**This architecture provides a secure, maintainable, and production-ready self-hosted cloud platform.**
|
||||
Reference in New Issue
Block a user