Zarządzanie kontenerami Docker

Dokumentacja dla deweloperów ReadyNextOS

Ostatnia aktualizacja: 2025-12-28

Spis treści

1. Architektura
2. Lista kontenerów
3. Podstawowe operacje
4. Zarządzanie poszczególnymi serwisami
5. Logi i diagnostyka
6. Watchtower - automatyczne aktualizacje
7. Troubleshooting

---

Architektura

┌─────────────────────────────────────────────────────────────────────────┐
│                         ReadyNextOS - Docker Stack                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────────────────┐  │
│  │   Nginx      │────▶│   PHP-FPM    │────▶│  Docker Containers       │  │
│  │   (host)     │     │   (host)     │     │                          │  │
│  │   :80/:443   │     │   8.4        │     │  ┌────────────────────┐  │  │
│  └──────────────┘     └──────────────┘     │  │ PostgreSQL 18      │  │  │
│                                             │  │ ready4docs-db:5433 │  │  │
│                                             │  └────────────────────┘  │  │
│                                             │                          │  │
│                                             │  ┌────────────────────┐  │  │
│                                             │  │ Redis 7            │  │  │
│                                             │  │ :6379              │  │  │
│                                             │  └────────────────────┘  │  │
│                                             │                          │  │
│                                             │  ┌────────────────────┐  │  │
│                                             │  │ MinIO (S3)         │  │  │
│                                             │  │ :9000/:9001        │  │  │
│                                             │  └────────────────────┘  │  │
│                                             │                          │  │
│                                             │  ┌────────────────────┐  │  │
│                                             │  │ Keycloak 24        │  │  │
│                                             │  │ :8081              │  │  │
│                                             │  └────────────────────┘  │  │
│                                             │                          │  │
│                                             │  ┌────────────────────┐  │  │
│                                             │  │ Reverb (WebSocket) │  │  │
│                                             │  │ :6001              │  │  │
│                                             │  └────────────────────┘  │  │
│                                             │                          │  │
│                                             │  ┌────────────────────┐  │  │
│                                             │  │ Queue Worker       │  │  │
│                                             │  └────────────────────┘  │  │
│                                             └──────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

Lista kontenerów

Kontener	Obraz	Port	Opis
ready4docs-db	pgvector/pgvector:pg18	5433	Baza danych PostgreSQL z pgvector
readynextos-redis	redis:7-alpine	6379	Cache, sesje, kolejki
ready4docs-minio	minio/minio:latest	9000, 9001	S3-compatible storage
ready4docs-keycloak	keycloak:24.0	8081	OIDC Identity Provider
readynextos-reverb	ghcr.io/milocha/ready4docs-php	6001	WebSocket (Laravel Reverb)
readynextos-queue	ghcr.io/milocha/ready4docs-php	-	Background jobs
ready4docs-livekit	livekit/livekit-server	7880, 7882/udp	WebRTC video/audio
readynextos-donut-ocr	ghcr.io/milocha/ready4docs-donut-ocr	8885	AI OCR dla faktur
ready4docs-tesseract	hertzg/tesseract-server	8884	OCR ogólnego przeznaczenia
readynextos-watchtower	containrrr/watchtower	-	Auto-update kontenerów

---

Podstawowe operacje

Lokalizacja docker-compose

cd /home/ready4docs

Status wszystkich kontenerów

# Szybki podgląd
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Szczegółowy status z healthcheck
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

Uruchamianie i zatrzymywanie

# Uruchom wszystkie serwisy
docker compose up -d

# Uruchom konkretny serwis
docker compose up -d reverb

# Zatrzymaj wszystkie
docker compose down

# Zatrzymaj konkretny kontener
docker stop readynextos-reverb

# Restart kontenera
docker restart ready4docs-db

Przebudowa kontenerów

# Po zmianie docker-compose.yml
docker compose up -d --force-recreate

# Z przebudową obrazu
docker compose build --no-cache reverb
docker compose up -d reverb

---

Zarządzanie poszczególnymi serwisami

PostgreSQL (ready4docs-db)

# Połączenie z bazą
docker exec -it ready4docs-db psql -U ready4docs

# Backup bazy (alternatywnie do systemd)
docker exec ready4docs-db pg_dump -U ready4docs ready4docs | gzip > backup.sql.gz

# Sprawdź logi
docker logs ready4docs-db --tail 100

# Sprawdź healthcheck
docker exec ready4docs-db pg_isready -U ready4docs

Redis

# Połączenie z Redis CLI
docker exec -it readynextos-redis redis-cli

# Sprawdź pamięć
docker exec readynextos-redis redis-cli info memory

# Wyczyść cache
docker exec readynextos-redis redis-cli FLUSHALL

# Monitor w czasie rzeczywistym
docker exec readynextos-redis redis-cli MONITOR

MinIO (S3 Storage)

# Konsola webowa: http://localhost:9001
# Login: minio / minio123 (z .env)

# Sprawdź buckety
docker exec ready4docs-minio mc ls local

# Logi
docker logs ready4docs-minio --tail 50

Keycloak (OIDC)

# Konsola admin: http://localhost:8081
# Login: admin / admin (z .env)

# Logi
docker logs ready4docs-keycloak --tail 100

# Restart po zmianie konfiguracji
docker restart ready4docs-keycloak

Reverb (WebSocket)

# Status
docker logs readynextos-reverb --tail 50

# Restart
docker restart readynextos-reverb

# Test połączenia WebSocket
curl -v http://localhost:6001

Queue Worker

# Status kolejek
docker exec readynextos-queue php artisan queue:monitor

# Logi
docker logs readynextos-queue --tail 100 -f

# Restart po zmianie kodu
docker restart readynextos-queue

# Wyczyść nieudane joby
docker exec readynextos-queue php artisan queue:flush

Donut OCR (AI Invoice Extraction)

# Status
docker logs readynextos-donut-ocr --tail 50

# Test health
curl http://localhost:8885/.well-known/health/ready

# Uwaga: Pierwsze uruchomienie pobiera model (~1.5GB)
# Może to potrwać kilka minut

---

Logi i diagnostyka

Podgląd logów

# Wszystkie kontenery
docker compose logs -f

# Konkretny serwis
docker compose logs -f reverb

# Ostatnie N linii
docker logs ready4docs-db --tail 100

# Z timestampami
docker logs ready4docs-db --tail 100 -t

Sprawdzanie healthcheck

# Status wszystkich healthchecków
docker ps --format "table {{.Names}}\t{{.Status}}"

# Szczegóły healthcheck kontenera
docker inspect --format='{{json .State.Health}}' ready4docs-db | jq

Zasoby (CPU/RAM)

# Zużycie zasobów przez kontenery
docker stats --no-stream

# Ciągły monitoring
docker stats

Inspekcja kontenera

# Pełna konfiguracja
docker inspect ready4docs-db

# Tylko zmienne środowiskowe
docker inspect ready4docs-db --format='{{range .Config.Env}}{{println .}}{{end}}'

# Wolumeny
docker inspect ready4docs-db --format='{{json .Mounts}}' | jq

---

Watchtower - automatyczne aktualizacje

Watchtower automatycznie aktualizuje kontenery gdy pojawi się nowa wersja obrazu na GitHub Container Registry.

Konfiguracja

# Tryb tylko monitorowanie (domyślnie wyłączony)
WATCHTOWER_MONITOR_ONLY=false

# Interwał sprawdzania (co 6 godzin)
WATCHTOWER_POLL_INTERVAL=21600

Status

# Logi Watchtower
docker logs readynextos-watchtower --tail 50

# Sprawdź ostatnią aktualizację
docker logs readynextos-watchtower 2>&1 | grep -i update

Ręczne wymuszenie aktualizacji

# Zaktualizuj konkretny kontener
docker pull ghcr.io/milocha/ready4docs-php:latest
docker compose up -d reverb queue-worker

# Zaktualizuj wszystkie
docker compose pull
docker compose up -d

Wyłączenie auto-update dla kontenera

Dodaj label w docker-compose.yml:

services:
  db:
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

---

Troubleshooting

Kontener nie startuje

# 1. Sprawdź logi
docker logs ready4docs-db --tail 100

# 2. Sprawdź czy port jest zajęty
sudo lsof -i :5433

# 3. Sprawdź konfigurację
docker compose config

# 4. Usuń i utwórz ponownie
docker compose down
docker compose up -d

Kontener “unhealthy”

# Sprawdź szczegóły healthcheck
docker inspect --format='{{json .State.Health}}' ready4docs-db | jq

# Ręcznie uruchom komendę healthcheck
docker exec ready4docs-db pg_isready -U ready4docs

Brak miejsca na dysku

# Sprawdź wolumeny
docker system df

# Usuń nieużywane obrazy i wolumeny
docker system prune -a --volumes

# Usuń tylko nieużywane obrazy
docker image prune -a

Reset kontenera do stanu początkowego

# UWAGA: To usuwa wszystkie dane!

# Zatrzymaj i usuń kontener z wolumenem
docker compose down -v db

# Usuń katalog danych
sudo rm -rf /home/ready4docs/postgres-data

# Uruchom ponownie (utworzy nową bazę)
docker compose up -d db

Problemy z siecią Docker

# Sprawdź sieci
docker network ls

# Usuń i utwórz sieć ponownie
docker network rm readynextos-network
docker compose up -d

---

Zmienne środowiskowe

Wszystkie zmienne są zdefiniowane w /home/ready4docs/.env:

Zmienna	Domyślna wartość	Opis
DB_USERNAME	readynextos	Użytkownik PostgreSQL
DB_PASSWORD	(z .env)	Hasło PostgreSQL
DB_DATABASE	readynextos	Nazwa bazy
DB_HOST_PORT	5433	Port PostgreSQL na hoście
REDIS_PORT	6379	Port Redis
MINIO_ROOT_USER	minio	Użytkownik MinIO
MINIO_ROOT_PASSWORD	(z .env)	Hasło MinIO
KEYCLOAK_ADMIN	admin	Admin Keycloak
KEYCLOAK_ADMIN_PASSWORD	(z .env)	Hasło admin Keycloak
REVERB_PORT	6001	Port WebSocket
GHCR_OWNER	milocha	Owner obrazów na GHCR

---

Przydatne aliasy

Dodaj do ~/.bashrc:

# Docker shortcuts
alias dps='docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"'
alias dlogs='docker compose logs -f'
alias dstats='docker stats --no-stream'
alias dexec='docker exec -it'

# ReadyNextOS specific
alias r4d-db='docker exec -it ready4docs-db psql -U ready4docs'
alias r4d-redis='docker exec -it readynextos-redis redis-cli'
alias r4d-logs='cd /home/ready4docs && docker compose logs -f'