Lukas
90f4c6239c
- fail2ban: 0.5 CPU / 128M memory limit, 0.1 CPU / 64M reserved - backend: 2.0 CPU / 512M memory limit, 1.0 CPU / 256M reserved - frontend: 0.5 CPU / 128M memory limit, 0.25 CPU / 64M reserved Prevents 'noisy neighbor' scenarios where one container exhausts host resources (CPU, memory, disk). Limits are hard caps; reservations guarantee minimum allocation to prevent OOM kills and ensure responsive service even under load. Fixes resource contention issue in production and staging environments. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
# Deployment Guide
|
||
|
||
## Docker Compose Setup
|
||
|
||
BanGUI is designed to run in Docker containers with proper resource isolation and limits to prevent "noisy neighbor" scenarios where one container exhausts host resources.
|
||
|
||
---
|
||
|
||
## Resource Allocation
|
||
|
||
All containers have hard limits (max usage) and soft reservations (guaranteed allocation). This ensures:
|
||
- **Isolation**: A misbehaving container cannot crash others or the host
|
||
- **Predictability**: Reservations guarantee minimum resources even under load
|
||
- **Efficiency**: Unused reserved capacity can be borrowed by other containers
|
||
|
||
### Container Resource Limits
|
||
|
||
| Container | Limit CPU | Limit Memory | Reserved CPU | Reserved Memory | Purpose |
|
||
|-----------|-----------|--------------|--------------|-----------------|---------|
|
||
| **fail2ban** | 0.5 | 128M | 0.1 | 64M | Monitors logs, bans IPs—typically idle |
|
||
| **backend** | 2.0 | 512M | 1.0 | 256M | Core app: database, fail2ban API, config management |
|
||
| **frontend** | 0.5 | 128M | 0.25 | 64M | Nginx: serves SPA + API proxy |
|
||
|
||
### Rationale
|
||
|
||
- **fail2ban**: Lightweight log monitoring. Occasionally CPU spikes during ban processing but memory usage is minimal.
|
||
- **backend**: Heavy lifting—Python runtime, SQLite database, background jobs. May need extra memory for large blocklists. Reservation of 1.0 CPU ensures responsive API even when frontend is busy.
|
||
- **frontend**: Nginx is efficient. Limit of 0.5 CPU and 128M memory is more than sufficient for reverse proxy duties.
|
||
|
||
---
|
||
|
||
## Memory Considerations
|
||
|
||
### Backend Memory Requirements
|
||
|
||
The backend typically runs in 256–512M under normal load. Memory usage depends on:
|
||
- **Blocklist size**: Large blocklists (>1M entries) require more heap space
|
||
- **Cache warmth**: First query after startup may require more memory as caches fill
|
||
- **Concurrent connections**: Each active user session uses a small amount of memory
|
||
|
||
**Tuning:** If you see OOM kills in logs, increase backend limits and reservations (e.g., 1024M limit). Test under realistic load before finalizing.
|
||
|
||
### Frontend Memory Usage
|
||
|
||
Nginx is typically <50M. If you see memory pressure on frontend, check for:
|
||
- Misconfigured cache headers on static assets
|
||
- Large log volumes (nginx access logs)
|
||
|
||
---
|
||
|
||
## Docker Swarm & Kubernetes
|
||
|
||
For production deployments using orchestration platforms:
|
||
|
||
### Docker Swarm
|
||
|
||
The `deploy` sections in `docker-compose.yml` are compatible with `docker stack deploy`:
|
||
|
||
```bash
|
||
docker stack deploy -c Docker/docker-compose.yml bangui
|
||
```
|
||
|
||
Swarm respects the same `limits` and `reservations` fields.
|
||
|
||
### Kubernetes
|
||
|
||
For Kubernetes, translate resource constraints to equivalent `resources` fields in your deployment manifests:
|
||
|
||
```yaml
|
||
containers:
|
||
- name: backend
|
||
image: git.lpl-mind.de/lukas.pupkalipinski/bangui/backend:latest
|
||
resources:
|
||
limits:
|
||
cpu: "2"
|
||
memory: "512Mi"
|
||
requests:
|
||
cpu: "1"
|
||
memory: "256Mi"
|
||
```
|
||
|
||
Kubernetes equivalent mappings:
|
||
- Docker `deploy.limits` → Kubernetes `resources.limits`
|
||
- Docker `deploy.reservations` → Kubernetes `resources.requests`
|
||
|
||
---
|
||
|
||
## Monitoring Resource Usage
|
||
|
||
### Docker Compose (Development)
|
||
|
||
```bash
|
||
docker stats
|
||
```
|
||
|
||
Shows real-time CPU and memory usage for all running containers.
|
||
|
||
### Production (Docker Swarm / Kubernetes)
|
||
|
||
Use native monitoring:
|
||
- **Docker Swarm**: Prometheus + Grafana
|
||
- **Kubernetes**: Metrics Server + dashboard or Prometheus
|
||
|
||
---
|
||
|
||
## Environment Variables
|
||
|
||
Resource limits are configured in `Docker/docker-compose.yml` and cannot be overridden via environment variables. To adjust limits:
|
||
|
||
1. Edit `Docker/docker-compose.yml`
|
||
2. Modify the `deploy.limits` and `deploy.reservations` sections
|
||
3. Restart containers: `make down && make up`
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
| Issue | Symptom | Solution |
|
||
|-------|---------|----------|
|
||
| Backend OOM kills | "Exit code 137" in logs | Increase backend `memory` limit |
|
||
| Throttling | CPU at 100%, requests slow | Increase CPU limit or optimize code |
|
||
| Service startup timeout | Containers not becoming "healthy" | Increase reservation to guarantee capacity at startup |
|
||
| Host unresponsive | System-wide lag | Reduce container limits to prevent host starvation |
|
||
|
||
---
|
||
|
||
## Next Steps
|
||
|
||
- **Development**: Run `make up` to start with default limits
|
||
- **Staging**: Test with realistic data volumes and monitor resource usage
|
||
- **Production**: Adjust limits based on observed usage patterns, then commit changes
|