refactoring Single Source of Truth
This commit is contained in:
@@ -0,0 +1,299 @@
|
||||
# Docker-Troubleshooting und Best Practices
|
||||
|
||||
---
|
||||
guideline_type: "technology"
|
||||
scope: "docker-troubleshooting"
|
||||
audience: ["developers", "devops", "ai-assistants"]
|
||||
last_updated: "2025-09-13"
|
||||
dependencies: ["docker-overview.md", "docker-architecture.md", "docker-development.md"]
|
||||
related_files: ["docker-compose.yml", "scripts/validate-docker-consistency.sh", "scripts/docker-versions-update.sh"]
|
||||
ai_context: "Troubleshooting common Docker issues, debug commands, and comprehensive best practices"
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Häufige Probleme und Lösungen
|
||||
|
||||
#### 🚫 Port-Konflikte
|
||||
|
||||
```bash
|
||||
# Überprüfe, welche Ports verwendet werden
|
||||
netstat -tulpn | grep :8080
|
||||
lsof -i :8080
|
||||
|
||||
# Stoppe konfligierende Services
|
||||
docker-compose down
|
||||
sudo systemctl stop apache2 # Falls Apache läuft
|
||||
```
|
||||
|
||||
#### 🐌 Langsame Startup-Zeiten
|
||||
|
||||
```bash
|
||||
# Überprüfe Container-Ressourcen
|
||||
docker stats
|
||||
|
||||
# Health-Check Logs analysieren
|
||||
docker-compose logs ping-service | grep health
|
||||
|
||||
# Java Startup optimieren
|
||||
export JAVA_OPTS="$JAVA_OPTS -XX:TieredStopAtLevel=1 -noverify"
|
||||
```
|
||||
|
||||
#### 💾 Disk-Space Probleme
|
||||
|
||||
```bash
|
||||
# Docker-Cleanup
|
||||
docker system prune -a --volumes
|
||||
docker volume prune
|
||||
|
||||
# Log-Rotation für Container
|
||||
docker-compose logs --tail=1000 > /dev/null # Truncate logs
|
||||
```
|
||||
|
||||
#### 🌐 Service Discovery Issues
|
||||
|
||||
```bash
|
||||
# Consul Status prüfen
|
||||
curl -s http://localhost:8500/v1/health/state/any | jq
|
||||
|
||||
# Service Registration überprüfen
|
||||
curl -s http://localhost:8500/v1/catalog/services | jq
|
||||
|
||||
# DNS-Resolution testen
|
||||
docker-compose exec api-gateway nslookup ping-service
|
||||
```
|
||||
|
||||
### Debug-Kommandos
|
||||
|
||||
```bash
|
||||
# Container introspection
|
||||
docker-compose exec SERVICE_NAME sh
|
||||
docker-compose exec postgres psql -U meldestelle -d meldestelle
|
||||
|
||||
# Live-Monitoring
|
||||
docker-compose top
|
||||
watch -n 1 'docker-compose ps'
|
||||
|
||||
# Memory und CPU-Usage
|
||||
docker stats $(docker-compose ps -q)
|
||||
|
||||
# Detailed service logs
|
||||
docker-compose logs -f --tail=50 SERVICE_NAME
|
||||
```
|
||||
|
||||
## 🎯 AI-Assistenten: Troubleshooting-Schnellreferenz
|
||||
|
||||
### Häufige Befehle
|
||||
|
||||
| Problem | Befehl | Beschreibung |
|
||||
|---------|---------|--------------|
|
||||
| Port belegt | `netstat -tulpn \| grep :<port>` | Port-Nutzung prüfen |
|
||||
| Service startet nicht | `docker-compose logs <service>` | Service-Logs anzeigen |
|
||||
| Container hängt | `docker stats` | Ressourcenverbrauch |
|
||||
| DNS-Probleme | `docker-compose exec <service> nslookup <target>` | DNS-Resolution testen |
|
||||
| Disk voll | `docker system prune -a --volumes` | Cleanup durchführen |
|
||||
|
||||
### Debug-Workflows
|
||||
|
||||
#### Service startet nicht
|
||||
1. `docker-compose ps` - Status prüfen
|
||||
2. `docker-compose logs <service>` - Logs analysieren
|
||||
3. `docker-compose exec <service> sh` - Container inspizieren
|
||||
4. Health-Check-Endpoint testen
|
||||
|
||||
#### Performance-Probleme
|
||||
1. `docker stats` - Ressourcenverbrauch
|
||||
2. `docker-compose top` - Prozess-Übersicht
|
||||
3. JVM-Parameter optimieren
|
||||
4. Resource-Limits anpassen
|
||||
|
||||
#### Netzwerk-Probleme
|
||||
1. `docker network ls` - Netzwerke auflisten
|
||||
2. `docker-compose exec <service> ping <target>` - Connectivity testen
|
||||
3. Consul Service-Discovery prüfen
|
||||
4. DNS-Resolution validieren
|
||||
|
||||
## ✅ Best Practices
|
||||
|
||||
### 🔐 Security Best Practices
|
||||
|
||||
1. **Non-Root Users**: Alle Container laufen mit dedizierten Non-Root-Usern
|
||||
2. **Minimal Base Images**: Alpine Linux für kleinste Angriffsfläche
|
||||
3. **Secrets Management**: Externe Secret-Stores für Production
|
||||
4. **Network Isolation**: Dedizierte Docker-Networks
|
||||
5. **Regular Updates**: Automatische Security-Updates für Base Images
|
||||
|
||||
### ⚡ Performance Best Practices
|
||||
|
||||
1. **Multi-Stage Builds**: Minimale Runtime-Images
|
||||
2. **Layer Caching**: Optimale COPY-Reihenfolge in Dockerfiles
|
||||
3. **Resource Limits**: Definierte Memory und CPU-Limits
|
||||
4. **Health Checks**: Proaktive Container-Health-Überwachung
|
||||
5. **JVM Tuning**: Container-aware JVM-Settings
|
||||
|
||||
### 🧹 Wartung Best Practices
|
||||
|
||||
1. **Version Pinning**: Explizite Image-Versionen in Production
|
||||
2. **Backup Strategies**: Automatische Volume-Backups
|
||||
3. **Log Rotation**: Begrenzte Log-Datei-Größen
|
||||
4. **Documentation**: Aktuelle README-Dateien pro Service
|
||||
5. **Testing**: Automatisierte Container-Tests
|
||||
|
||||
### 🎯 Zentrale Verwaltung Best Practices
|
||||
|
||||
#### Single Source of Truth Prinzipien
|
||||
|
||||
```bash
|
||||
# ✅ RICHTIG - Zentrale Version-Updates
|
||||
./scripts/docker-versions-update.sh update java 22
|
||||
./scripts/docker-versions-update.sh sync
|
||||
|
||||
# ❌ FALSCH - Manuelle Bearbeitung von Dockerfiles
|
||||
vim dockerfiles/services/ping-service/Dockerfile # Version hardcoden
|
||||
```
|
||||
|
||||
> **🤖 AI-Assistant Hinweis:**
|
||||
> Verwende immer das zentrale Versionssystem:
|
||||
> - **Updates:** `./scripts/docker-versions-update.sh update <component> <version>`
|
||||
> - **Validierung:** `./scripts/validate-docker-consistency.sh`
|
||||
> - **Template-Updates:** `./scripts/generate-compose-files.sh`
|
||||
|
||||
#### Port-Verwaltung Richtlinien
|
||||
|
||||
1. **Immer zentrale Port-Registry verwenden**:
|
||||
```toml
|
||||
# docker/versions.toml - Port-Definitionen
|
||||
[service-ports]
|
||||
new-service = 8089 # Nächster verfügbarer Port
|
||||
```
|
||||
|
||||
2. **Port-Konflikte vor Deployment prüfen**:
|
||||
```bash
|
||||
./scripts/validate-docker-consistency.sh
|
||||
```
|
||||
|
||||
3. **Port-Ranges einhalten**:
|
||||
- Infrastructure: 8081-8088
|
||||
- Services: 8082-8099
|
||||
- Monitoring: 9090-9099
|
||||
- Clients: 4000-4099
|
||||
|
||||
#### Environment-Overrides Standards
|
||||
|
||||
1. **Environment-spezifische Konfigurationen nutzen**:
|
||||
```bash
|
||||
# Development
|
||||
export DOCKER_ENVIRONMENT=development
|
||||
|
||||
# Production
|
||||
export DOCKER_ENVIRONMENT=production
|
||||
```
|
||||
|
||||
2. **Konsistente Health-Check-Konfigurationen**:
|
||||
```toml
|
||||
[environments.production]
|
||||
health-check-interval = "15s"
|
||||
health-check-timeout = "3s"
|
||||
health-check-retries = 3
|
||||
```
|
||||
|
||||
#### Template-System Richtlinien
|
||||
|
||||
1. **Compose-Files aus Templates generieren**:
|
||||
```bash
|
||||
# Automatische Generierung bevorzugen
|
||||
./scripts/generate-compose-files.sh
|
||||
|
||||
# Manuelle Bearbeitung nur bei spezifischen Anpassungen
|
||||
```
|
||||
|
||||
2. **Service-Kategorien korrekt zuordnen**:
|
||||
- `services/`: Domain-Services (ping, members, horses)
|
||||
- `infrastructure/`: Platform-Services (gateway, auth, monitoring)
|
||||
- `clients/`: Frontend-Anwendungen (web-app, desktop-app)
|
||||
|
||||
#### Validierung und Konsistenz
|
||||
|
||||
1. **Regelmäßige Konsistenz-Prüfungen**:
|
||||
```bash
|
||||
# Bei jedem Build
|
||||
./scripts/validate-docker-consistency.sh
|
||||
|
||||
# In CI/CD Pipeline integrieren
|
||||
```
|
||||
|
||||
2. **Build-Args Konsistenz**:
|
||||
```dockerfile
|
||||
# ✅ RICHTIG - Zentrale Referenz
|
||||
ARG GRADLE_VERSION
|
||||
ARG JAVA_VERSION
|
||||
|
||||
# ❌ FALSCH - Hardcodierte Versionen
|
||||
ARG GRADLE_VERSION=9.0.0
|
||||
```
|
||||
|
||||
#### IDE-Integration Best Practices
|
||||
|
||||
1. **JSON Schema für Validierung aktivieren**:
|
||||
```json
|
||||
{
|
||||
"yaml.schemas": {
|
||||
"./docker/schemas/versions-schema.json": "docker/versions.toml"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Automatisierte Tasks nutzen**:
|
||||
- Docker: Show Versions
|
||||
- Docker: Validate Consistency
|
||||
- Docker: Build All Services
|
||||
|
||||
### 🚀 Entwickler-Workflow Best Practices
|
||||
|
||||
#### Neuen Service hinzufügen
|
||||
|
||||
```bash
|
||||
# 1. Port in versions.toml reservieren
|
||||
echo "new-service = 8089" >> docker/versions.toml
|
||||
|
||||
# 2. Template-basierten Service erstellen
|
||||
./scripts/generate-compose-files.sh
|
||||
|
||||
# 3. Dockerfile aus Template erstellen
|
||||
cp dockerfiles/templates/spring-boot-service.Dockerfile \
|
||||
dockerfiles/services/new-service/Dockerfile
|
||||
|
||||
# 4. Build-Args und Environment synchronisieren
|
||||
./scripts/docker-versions-update.sh sync
|
||||
|
||||
# 5. Konsistenz validieren
|
||||
./scripts/validate-docker-consistency.sh
|
||||
```
|
||||
|
||||
#### Version-Updates durchführen
|
||||
|
||||
```bash
|
||||
# 1. Aktuelle Versionen prüfen
|
||||
./scripts/docker-versions-update.sh show
|
||||
|
||||
# 2. Spezifische Version aktualisieren
|
||||
./scripts/docker-versions-update.sh update java 22
|
||||
|
||||
# 3. Alle Build-Args synchronisieren
|
||||
./scripts/docker-versions-update.sh sync
|
||||
|
||||
# 4. Services neu bauen
|
||||
docker-compose build --no-cache
|
||||
|
||||
# 5. System-Tests durchführen
|
||||
docker-compose up -d && make test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Navigation:**
|
||||
- [Docker-Overview](./docker-overview.md) - Grundlagen und Philosophie
|
||||
- [Docker-Architecture](./docker-architecture.md) - Container-Services und Struktur
|
||||
- [Docker-Development](./docker-development.md) - Entwicklungsworkflow
|
||||
- [Docker-Production](./docker-production.md) - Production-Deployment
|
||||
- [Docker-Monitoring](./docker-monitoring.md) - Observability
|
||||
Reference in New Issue
Block a user