komga/ai-docs/docker-setup.md

Docker Setup for Komga with PostgreSQL

Overview

Docker Compose setup để chạy Komga với PostgreSQL cho development và testing.

File Structure

1. docker-compose.yml

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: komga-postgres
    environment:
      POSTGRES_DB: komga
      POSTGRES_USER: komga
      POSTGRES_PASSWORD: komga123
    ports:
      - "5433:5432"  # Port 5433 để tránh conflict với local PostgreSQL
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U komga"]
      interval: 10s
      timeout: 5s
      retries: 5

  komga:
    build:
      context: .
      dockerfile: docker/Dockerfile
    container_name: komga-backend
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SPRING_PROFILES_ACTIVE: docker
      KOMGA_DATABASE_TYPE: postgresql
      KOMGA_DATABASE_URL: jdbc:postgresql://postgres:5432/komga
      KOMGA_DATABASE_USERNAME: komga
      KOMGA_DATABASE_PASSWORD: komga123
      KOMGA_CONFIG_DIR: /config
    ports:
      - "25600:25600"
    volumes:
      - komga_config:/config
      - ./data:/data:ro
    restart: unless-stopped

volumes:
  postgres_data:
  komga_config:

2. docker-compose-test.yml (cho testing)

version: '3.8'

services:
  postgres-test:
    image: postgres:16-alpine
    container_name: komga-postgres-test
    environment:
      POSTGRES_DB: komga_test
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5433:5432"
    volumes:
      - postgres_test_data:/var/lib/postgresql/data
      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    command: ["postgres", "-c", "log_statement=all"]  # Log all SQL for debugging

volumes:
  postgres_test_data:

3. docker/postgres/init.sql

-- PostgreSQL initialization script for Komga
-- Creates necessary extensions and sets up database

-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "pg_trgm"; -- For text search/pattern matching
CREATE EXTENSION IF NOT EXISTS "unaccent"; -- For accent removal (similar to UDF_STRIP_ACCENTS)

Environment Variables

PostgreSQL Container:

• POSTGRES_DB: Database name (default: komga)
• POSTGRES_USER: Database user (default: komga)
• POSTGRES_PASSWORD: Database password (default: komga123)

Komga Container:

• SPRING_PROFILES_ACTIVE: Spring profile (docker)
• KOMGA_DATABASE_TYPE: Database type (postgresql)
• KOMGA_DATABASE_URL: JDBC URL (jdbc:postgresql://postgres:5432/komga)
• KOMGA_DATABASE_USERNAME: Database username
• KOMGA_DATABASE_PASSWORD: Database password
• KOMGA_CONFIG_DIR: Configuration directory (/config)

Usage Commands

1. Start PostgreSQL only:

docker-compose up -d postgres

2. Start full stack (PostgreSQL + Komga):

docker-compose up -d

3. Stop all services:

docker-compose down

4. Stop and remove volumes:

docker-compose down -v

5. View logs:

# PostgreSQL logs
docker-compose logs postgres

# Komga logs
docker-compose logs komga

# All logs
docker-compose logs -f

6. Access PostgreSQL:

# Connect via psql
docker-compose exec postgres psql -U komga -d komga

# Connect from host
psql -h localhost -p 5433 -U komga -d komga

Scripts

run-local-with-postgres.sh

#!/bin/bash
# Script to run Komga locally with PostgreSQL

set -e

echo "Starting PostgreSQL container..."
docker-compose up -d postgres

echo "Waiting for PostgreSQL to be ready..."
sleep 5

echo "Building Komga..."
./gradlew :komga:build -x test

echo "Running Komga with PostgreSQL..."
SPRING_PROFILES_ACTIVE=docker \
KOMGA_DATABASE_TYPE=postgresql \
KOMGA_DATABASE_URL="jdbc:postgresql://localhost:5433/komga" \
KOMGA_DATABASE_USERNAME=komga \
KOMGA_DATABASE_PASSWORD=komga123 \
KOMGA_CONFIG_DIR="$HOME/.komga-postgres" \
./gradlew :komga:bootRun

echo "Komga is running at http://localhost:25600"
echo "PostgreSQL is running at localhost:5433"
echo "To stop: docker-compose down"

run-test-with-docker.sh

#!/bin/bash
# Script to run Komga tests with PostgreSQL using Docker Compose

set -e

echo "Starting PostgreSQL test container..."
docker-compose -f docker-compose-test.yml up -d postgres-test

echo "Waiting for PostgreSQL to be ready..."
sleep 10

echo "Building Komga..."
./gradlew :komga:build -x test

echo "Running tests with PostgreSQL..."
./gradlew :komga:test --tests "*PostgreSQL*" --info

echo "Running integration tests..."
./gradlew :komga:integrationTest --info

echo "Stopping test containers..."
docker-compose -f docker-compose-test.yml down

echo "Test completed!"

Port Configuration

Default Ports:

• PostgreSQL: 5433 (host) → 5432 (container)
• Komga API: 25600 (host) → 25600 (container)

Change Ports:

Để thay đổi ports, sửa file docker-compose.yml:

services:
  postgres:
    ports:
      - "NEW_PORT:5432"  # Thay NEW_PORT bằng port mong muốn
  
  komga:
    ports:
      - "NEW_PORT:25600"  # Thay NEW_PORT bằng port mong muốn

Volume Persistence

PostgreSQL Data:

• Volume: postgres_data
• Location: /var/lib/postgresql/data (container)
• Persists: Database data, tables, indexes

Komga Configuration:

• Volume: komga_config
• Location: /config (container)
• Contains: Application configuration, logs, Lucene indexes

Host Mounts:

• ./data:/data:ro: Read-only comic/manga library directory
• ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql: Init script

Health Checks

PostgreSQL Health Check:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U komga"]
  interval: 10s
  timeout: 5s
  retries: 5

Dependency Management:

Komga service sẽ đợi PostgreSQL healthy trước khi start:

depends_on:
  postgres:
    condition: service_healthy

Troubleshooting

1. Port Already in Use:

# Check what's using port 5433
lsof -i :5433

# Kill process using port
kill -9 $(lsof -t -i:5433)

2. PostgreSQL Connection Issues:

# Check PostgreSQL logs
docker-compose logs postgres

# Test connection
docker-compose exec postgres pg_isready -U komga

3. Reset Database:

# Stop and remove volumes
docker-compose down -v

# Start fresh
docker-compose up -d

4. Backup Database:

# Backup to file
docker-compose exec postgres pg_dump -U komga komga > backup.sql

# Restore from file
cat backup.sql | docker-compose exec -T postgres psql -U komga -d komga

Development Notes

1. Local Development vs Docker:

• Local: Chạy backend với ./gradlew :komga:bootRun, PostgreSQL trong Docker
• Docker: Chạy cả backend và PostgreSQL trong Docker

2. Test Configuration:

• Test containers sử dụng docker-compose-test.yml
• Database name: komga_test
• User: postgres (default PostgreSQL user)

3. Extensions Required:

• uuid-ossp: UUID generation
• pg_trgm: Text search and pattern matching
• unaccent: Accent removal (thay thế UDF_STRIP_ACCENTS)

4. Performance Considerations:

• Adjust shared_buffers và work_mem trong production
• Consider connection pooling với PgBouncer
• Monitor với pg_stat_statements extension