427 lines
17 KiB
Markdown
427 lines
17 KiB
Markdown
# 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.**
|