cleanup and Test pre-push hook
This commit is contained in:
415
DEPLOYMENT.md
415
DEPLOYMENT.md
@@ -1,272 +1,229 @@
|
||||
# Portfolio Deployment Guide
|
||||
|
||||
## Übersicht
|
||||
## Overview
|
||||
|
||||
Dieses Portfolio verwendet ein **optimiertes CI/CD-System** mit Docker für Production-Deployment. Das System ist darauf ausgelegt, hohen Traffic zu bewältigen und automatische Tests vor dem Deployment durchzuführen.
|
||||
This document covers all aspects of deploying the Portfolio application, including local development, CI/CD, and production deployment.
|
||||
|
||||
## 🚀 Features
|
||||
## Prerequisites
|
||||
|
||||
### ✅ **CI/CD Pipeline**
|
||||
- **Automatische Tests** vor jedem Deployment
|
||||
- **Security Scanning** mit Trivy
|
||||
- **Multi-Architecture Docker Builds** (AMD64 + ARM64)
|
||||
- **Health Checks** und Deployment-Verifikation
|
||||
- **Automatische Cleanup** alter Images
|
||||
- Docker and Docker Compose installed
|
||||
- Node.js 20+ for local development
|
||||
- Access to Gitea repository with Actions enabled
|
||||
|
||||
### ⚡ **Performance-Optimierungen**
|
||||
- **Multi-Stage Docker Build** für kleinere Images
|
||||
- **Nginx Load Balancer** mit Caching
|
||||
- **Gzip Compression** und optimierte Headers
|
||||
- **Rate Limiting** für API-Endpoints
|
||||
- **Resource Limits** für Container
|
||||
## Environment Setup
|
||||
|
||||
### 🔒 **Sicherheit**
|
||||
- **Non-root User** im Container
|
||||
- **Security Headers** (HSTS, CSP, etc.)
|
||||
- **SSL/TLS Termination** mit Nginx
|
||||
- **Vulnerability Scanning** in CI/CD
|
||||
### Required Secrets in Gitea
|
||||
|
||||
## 📁 Dateistruktur
|
||||
Configure these secrets in your Gitea repository (Settings → Secrets):
|
||||
|
||||
```
|
||||
├── .github/workflows/
|
||||
│ └── ci-cd.yml # CI/CD Pipeline
|
||||
├── scripts/
|
||||
│ ├── deploy.sh # Deployment-Skript
|
||||
│ └── monitor.sh # Monitoring-Skript
|
||||
├── docker-compose.prod.yml # Production Docker Compose
|
||||
├── nginx.conf # Nginx Konfiguration
|
||||
├── Dockerfile # Optimiertes Dockerfile
|
||||
└── env.example # Environment Template
|
||||
```
|
||||
| Secret Name | Description | Example |
|
||||
|-------------|-------------|---------|
|
||||
| `NEXT_PUBLIC_BASE_URL` | Public URL of your website | `https://dk0.dev` |
|
||||
| `MY_EMAIL` | Main email for contact form | `contact@dk0.dev` |
|
||||
| `MY_INFO_EMAIL` | Info email address | `info@dk0.dev` |
|
||||
| `MY_PASSWORD` | Password for main email | `your_email_password` |
|
||||
| `MY_INFO_PASSWORD` | Password for info email | `your_info_email_password` |
|
||||
| `ADMIN_BASIC_AUTH` | Admin basic auth for protected areas | `admin:your_secure_password` |
|
||||
|
||||
## 🛠️ Setup
|
||||
### Local Environment
|
||||
|
||||
### 1. **Environment Variables**
|
||||
```bash
|
||||
# Kopiere die Beispiel-Datei
|
||||
cp env.example .env
|
||||
1. Copy environment template:
|
||||
```bash
|
||||
cp env.example .env
|
||||
```
|
||||
|
||||
# Bearbeite die .env Datei mit deinen Werten
|
||||
nano .env
|
||||
```
|
||||
2. Update `.env` with your values:
|
||||
```bash
|
||||
NEXT_PUBLIC_BASE_URL=https://dk0.dev
|
||||
MY_EMAIL=contact@dk0.dev
|
||||
MY_INFO_EMAIL=info@dk0.dev
|
||||
MY_PASSWORD=your_email_password
|
||||
MY_INFO_PASSWORD=your_info_email_password
|
||||
ADMIN_BASIC_AUTH=admin:your_secure_password
|
||||
```
|
||||
|
||||
### 2. **GitHub Secrets & Variables**
|
||||
Konfiguriere in deinem GitHub Repository:
|
||||
## Deployment Methods
|
||||
|
||||
**Secrets:**
|
||||
- `GITHUB_TOKEN` (automatisch verfügbar)
|
||||
- `GHOST_API_KEY`
|
||||
- `MY_PASSWORD`
|
||||
- `MY_INFO_PASSWORD`
|
||||
|
||||
**Variables:**
|
||||
- `NEXT_PUBLIC_BASE_URL`
|
||||
- `GHOST_API_URL`
|
||||
- `MY_EMAIL`
|
||||
- `MY_INFO_EMAIL`
|
||||
|
||||
### 3. **SSL-Zertifikate**
|
||||
```bash
|
||||
# Erstelle SSL-Verzeichnis
|
||||
mkdir -p ssl
|
||||
|
||||
# Kopiere deine SSL-Zertifikate
|
||||
cp your-cert.pem ssl/cert.pem
|
||||
cp your-key.pem ssl/key.pem
|
||||
```
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### **Automatisches Deployment**
|
||||
Das System deployt automatisch bei Push auf den `production` Branch:
|
||||
### 1. Local Development
|
||||
|
||||
```bash
|
||||
# Code auf production Branch pushen
|
||||
git push origin production
|
||||
# Start all services
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f portfolio
|
||||
|
||||
# Stop services
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### **Manuelles Deployment**
|
||||
### 2. CI/CD Pipeline (Automatic)
|
||||
|
||||
The CI/CD pipeline runs automatically on:
|
||||
- **Push to `main`**: Runs tests, linting, build, and security checks
|
||||
- **Push to `production`**: Full deployment including Docker build and deployment
|
||||
|
||||
#### Pipeline Steps:
|
||||
1. **Install dependencies** (`npm ci`)
|
||||
2. **Run linting** (`npm run lint`)
|
||||
3. **Run tests** (`npm run test`)
|
||||
4. **Build application** (`npm run build`)
|
||||
5. **Security scan** (`npm audit`)
|
||||
6. **Build Docker image** (production only)
|
||||
7. **Deploy with Docker Compose** (production only)
|
||||
|
||||
### 3. Manual Deployment
|
||||
|
||||
```bash
|
||||
# Lokales Deployment
|
||||
./scripts/deploy.sh production
|
||||
# Build and start services
|
||||
docker-compose up -d --build
|
||||
|
||||
# Oder mit npm
|
||||
npm run deploy
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### **Docker Commands**
|
||||
## Service Configuration
|
||||
|
||||
### Portfolio App
|
||||
- **Port**: 3000 (configurable via `PORT` environment variable)
|
||||
- **Health Check**: `http://localhost:3000/api/health`
|
||||
- **Environment**: Production
|
||||
- **Resources**: 512M memory limit, 0.5 CPU limit
|
||||
|
||||
### PostgreSQL Database
|
||||
- **Port**: 5432 (internal)
|
||||
- **Database**: `portfolio_db`
|
||||
- **User**: `portfolio_user`
|
||||
- **Password**: `portfolio_pass`
|
||||
- **Health Check**: `pg_isready`
|
||||
|
||||
### Redis Cache
|
||||
- **Port**: 6379 (internal)
|
||||
- **Health Check**: `redis-cli ping`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Secrets not loading**:
|
||||
- Run the debug workflow: Actions → Debug Secrets
|
||||
- Verify all secrets are set in Gitea
|
||||
- Check secret names match exactly
|
||||
|
||||
2. **Container won't start**:
|
||||
```bash
|
||||
# Check logs
|
||||
docker-compose logs portfolio
|
||||
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# Restart services
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
3. **Database connection issues**:
|
||||
```bash
|
||||
# Check PostgreSQL status
|
||||
docker-compose exec postgres pg_isready -U portfolio_user -d portfolio_db
|
||||
|
||||
# Check database logs
|
||||
docker-compose logs postgres
|
||||
```
|
||||
|
||||
4. **Redis connection issues**:
|
||||
```bash
|
||||
# Test Redis connection
|
||||
docker-compose exec redis redis-cli ping
|
||||
|
||||
# Check Redis logs
|
||||
docker-compose logs redis
|
||||
```
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Container starten
|
||||
npm run docker:compose
|
||||
# Check environment variables in container
|
||||
docker exec portfolio-app env | grep -E "(DATABASE_URL|REDIS_URL|NEXT_PUBLIC_BASE_URL)"
|
||||
|
||||
# Container stoppen
|
||||
npm run docker:down
|
||||
# Test health endpoints
|
||||
curl -f http://localhost:3000/api/health
|
||||
|
||||
# Health Check
|
||||
npm run health
|
||||
# View all service logs
|
||||
docker-compose logs --tail=50
|
||||
|
||||
# Check resource usage
|
||||
docker stats
|
||||
```
|
||||
|
||||
## 📊 Monitoring
|
||||
## Monitoring
|
||||
|
||||
### **Container Status**
|
||||
### Health Checks
|
||||
- **Portfolio App**: `http://localhost:3000/api/health`
|
||||
- **PostgreSQL**: `pg_isready` command
|
||||
- **Redis**: `redis-cli ping` command
|
||||
|
||||
### Logs
|
||||
```bash
|
||||
# Status anzeigen
|
||||
./scripts/monitor.sh status
|
||||
# Follow all logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Oder mit npm
|
||||
npm run monitor status
|
||||
# Follow specific service logs
|
||||
docker-compose logs -f portfolio
|
||||
docker-compose logs -f postgres
|
||||
docker-compose logs -f redis
|
||||
```
|
||||
|
||||
### **Health Check**
|
||||
## Security
|
||||
|
||||
### Security Scans
|
||||
- **NPM Audit**: Runs automatically in CI/CD
|
||||
- **Dependency Check**: Checks for known vulnerabilities
|
||||
- **Secret Detection**: Prevents accidental secret commits
|
||||
|
||||
### Best Practices
|
||||
- Never commit secrets to repository
|
||||
- Use environment variables for sensitive data
|
||||
- Regularly update dependencies
|
||||
- Monitor security advisories
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
### Database Backup
|
||||
```bash
|
||||
# Application Health
|
||||
./scripts/monitor.sh health
|
||||
# Create backup
|
||||
docker-compose exec postgres pg_dump -U portfolio_user portfolio_db > backup.sql
|
||||
|
||||
# Oder direkt
|
||||
curl http://localhost:3000/api/health
|
||||
# Restore backup
|
||||
docker-compose exec -T postgres psql -U portfolio_user portfolio_db < backup.sql
|
||||
```
|
||||
|
||||
### **Logs anzeigen**
|
||||
### Volume Backup
|
||||
```bash
|
||||
# Letzte 50 Zeilen
|
||||
./scripts/monitor.sh logs 50
|
||||
|
||||
# Live-Logs folgen
|
||||
./scripts/monitor.sh logs 100
|
||||
# Backup volumes
|
||||
docker run --rm -v portfolio_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz /data
|
||||
docker run --rm -v portfolio_redis_data:/data -v $(pwd):/backup alpine tar czf /backup/redis_backup.tar.gz /data
|
||||
```
|
||||
|
||||
### **Metriken**
|
||||
```bash
|
||||
# Detaillierte Metriken
|
||||
./scripts/monitor.sh metrics
|
||||
```
|
||||
## Performance Optimization
|
||||
|
||||
## 🔧 Wartung
|
||||
### Resource Limits
|
||||
- **Portfolio App**: 512M memory, 0.5 CPU
|
||||
- **PostgreSQL**: 256M memory, 0.25 CPU
|
||||
- **Redis**: Default limits
|
||||
|
||||
### **Container neustarten**
|
||||
```bash
|
||||
./scripts/monitor.sh restart
|
||||
```
|
||||
### Caching
|
||||
- **Next.js**: Built-in caching
|
||||
- **Redis**: Session and analytics caching
|
||||
- **Static Assets**: Served from CDN
|
||||
|
||||
### **Cleanup**
|
||||
```bash
|
||||
# Docker-Ressourcen bereinigen
|
||||
./scripts/monitor.sh cleanup
|
||||
```
|
||||
## Support
|
||||
|
||||
### **Updates**
|
||||
```bash
|
||||
# Neues Image pullen und deployen
|
||||
./scripts/deploy.sh production
|
||||
```
|
||||
|
||||
## 📈 Performance-Tuning
|
||||
|
||||
### **Nginx Optimierungen**
|
||||
- **Gzip Compression** aktiviert
|
||||
- **Static Asset Caching** (1 Jahr)
|
||||
- **API Rate Limiting** (10 req/s)
|
||||
- **Load Balancing** bereit für Skalierung
|
||||
|
||||
### **Docker Optimierungen**
|
||||
- **Multi-Stage Build** für kleinere Images
|
||||
- **Non-root User** für Sicherheit
|
||||
- **Health Checks** für automatische Recovery
|
||||
- **Resource Limits** (512MB RAM, 0.5 CPU)
|
||||
|
||||
### **Next.js Optimierungen**
|
||||
- **Standalone Output** für Docker
|
||||
- **Image Optimization** (WebP, AVIF)
|
||||
- **CSS Optimization** aktiviert
|
||||
- **Package Import Optimization**
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### **Container startet nicht**
|
||||
```bash
|
||||
# Logs prüfen
|
||||
./scripts/monitor.sh logs
|
||||
|
||||
# Status prüfen
|
||||
./scripts/monitor.sh status
|
||||
|
||||
# Neustarten
|
||||
./scripts/monitor.sh restart
|
||||
```
|
||||
|
||||
### **Health Check schlägt fehl**
|
||||
```bash
|
||||
# Manueller Health Check
|
||||
curl -v http://localhost:3000/api/health
|
||||
|
||||
# Container-Logs prüfen
|
||||
docker compose -f docker-compose.prod.yml logs portfolio
|
||||
```
|
||||
|
||||
### **Performance-Probleme**
|
||||
```bash
|
||||
# Resource-Usage prüfen
|
||||
./scripts/monitor.sh metrics
|
||||
|
||||
# Nginx-Logs prüfen
|
||||
docker compose -f docker-compose.prod.yml logs nginx
|
||||
```
|
||||
|
||||
### **SSL-Probleme**
|
||||
```bash
|
||||
# SSL-Zertifikate prüfen
|
||||
openssl x509 -in ssl/cert.pem -text -noout
|
||||
|
||||
# Nginx-Konfiguration testen
|
||||
docker compose -f docker-compose.prod.yml exec nginx nginx -t
|
||||
```
|
||||
|
||||
## 📋 CI/CD Pipeline
|
||||
|
||||
### **Workflow-Schritte**
|
||||
1. **Test** - Linting, Tests, Build
|
||||
2. **Security** - Trivy Vulnerability Scan
|
||||
3. **Build** - Multi-Arch Docker Image
|
||||
4. **Deploy** - Automatisches Deployment
|
||||
|
||||
### **Trigger**
|
||||
- **Push auf `main`** - Build nur
|
||||
- **Push auf `production`** - Build + Deploy
|
||||
- **Pull Request** - Test + Security
|
||||
|
||||
### **Monitoring**
|
||||
- **GitHub Actions** - Pipeline-Status
|
||||
- **Container Health** - Automatische Checks
|
||||
- **Resource Usage** - Monitoring-Skript
|
||||
|
||||
## 🔄 Skalierung
|
||||
|
||||
### **Horizontal Scaling**
|
||||
```yaml
|
||||
# In nginx.conf - weitere Backend-Server hinzufügen
|
||||
upstream portfolio_backend {
|
||||
least_conn;
|
||||
server portfolio:3000 max_fails=3 fail_timeout=30s;
|
||||
server portfolio-2:3000 max_fails=3 fail_timeout=30s;
|
||||
server portfolio-3:3000 max_fails=3 fail_timeout=30s;
|
||||
}
|
||||
```
|
||||
|
||||
### **Vertical Scaling**
|
||||
```yaml
|
||||
# In docker-compose.prod.yml - Resource-Limits erhöhen
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 1G
|
||||
cpus: '1.0'
|
||||
```
|
||||
|
||||
## 📞 Support
|
||||
|
||||
Bei Problemen:
|
||||
1. **Logs prüfen**: `./scripts/monitor.sh logs`
|
||||
2. **Status prüfen**: `./scripts/monitor.sh status`
|
||||
3. **Health Check**: `./scripts/monitor.sh health`
|
||||
4. **Container neustarten**: `./scripts/monitor.sh restart`
|
||||
For issues or questions:
|
||||
1. Check the troubleshooting section above
|
||||
2. Review CI/CD pipeline logs
|
||||
3. Run the debug workflow
|
||||
4. Check service health endpoints
|
||||
Reference in New Issue
Block a user