Skip to main content

Docker Deployment

Deploy Koreshield quickly using Docker containers for development and production environments.

Quick Start​

Pull Official Image​

docker pull Koreshield/Koreshield:latest

Run Container​

docker run -d \
  --name Koreshield \
  -p 8080:8080 \
  -e Koreshield_API_KEY=your_api_key \
  -e REDIS_URL=redis://redis:6379 \
  -e DATABASE_URL=postgresql://user:pass@postgres:5432/Koreshield \
  Koreshield/Koreshield:latest

Docker Compose​

Basic Setup​

# docker-compose.yml
version: '3.8'

services:
  Koreshield:
    image: Koreshield/Koreshield:latest
    ports:
      - "8080:8080"
    environment:
      - Koreshield_API_KEY=${Koreshield_API_KEY}
      - REDIS_URL=redis://redis:6379
      - DATABASE_URL=postgresql://postgres:password@postgres:5432/Koreshield
      - LOG_LEVEL=info
    depends_on:
      - redis
      - postgres
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=Koreshield
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  redis_data:
  postgres_data:

Start services:

docker-compose up -d

Production Setup​

# docker-compose.prod.yml
version: '3.8'

services:
  Koreshield:
    image: Koreshield/Koreshield:2.0.0
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G
    ports:
      - "8080:8080"
    environment:
      - Koreshield_ENV=production
      - Koreshield_API_KEY=${Koreshield_API_KEY}
      - REDIS_URL=redis://redis:6379
      - DATABASE_URL=${DATABASE_URL}
      - SENTRY_DSN=${SENTRY_DSN}
      - LOG_LEVEL=warn
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: always
    networks:
      - Koreshield_network

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - Koreshield
    networks:
      - Koreshield_network

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    networks:
      - Koreshield_network

networks:
  Koreshield_network:
    driver: bridge

volumes:
  redis_data:

Custom Dockerfile​

Build your own image:

FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Create non-root user
RUN useradd -m -u 1000 Koreshield && \
    chown -R Koreshield:Koreshield /app
USER Koreshield

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

# Run application
CMD ["python", "-m", "Koreshield.server"]

Build and run:

docker build -t my-Koreshield:latest .
docker run -d -p 8080:8080 my-Koreshield:latest

Environment Variables​

# Core
Koreshield_ENV=production
Koreshield_API_KEY=ks_prod_xxxxxxxxxxxx
Koreshield_BASE_URL=https://api.Koreshield.com

# Database
DATABASE_URL=postgresql://user:pass@host:5432/dbname

# Redis
REDIS_URL=redis://redis:6379
REDIS_PASSWORD=your_redis_password

# Security
SENSITIVITY=medium
ALLOW_ORIGINS=https://yourdomain.com

# Monitoring
SENTRY_DSN=https://xxx@sentry.io/xxx
PROMETHEUS_PORT=9090

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

Volume Mounts​

Configuration Files​

docker run -d \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/allowlist.json:/app/data/allowlist.json \
  -v $(pwd)/blocklist.json:/app/data/blocklist.json \
  Koreshield/Koreshield:latest

Persistent Data​

docker run -d \
  -v Koreshield_logs:/app/logs \
  -v Koreshield_data:/app/data \
  Koreshield/Koreshield:latest

Multi-Stage Build​

Optimized Dockerfile:

# Build stage
FROM python:3.11-slim AS builder

WORKDIR /app

COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /app/wheels -r requirements.txt

# Runtime stage
FROM python:3.11-slim

WORKDIR /app

COPY --from=builder /app/wheels /wheels
RUN pip install --no-cache /wheels/*

COPY . .

USER 1000:1000

EXPOSE 8080

CMD ["python", "-m", "Koreshield.server"]

Docker Swarm​

Deploy with Swarm:

# docker-stack.yml
version: '3.8'

services:
  Koreshield:
    image: Koreshield/Koreshield:latest
    deploy:
      replicas: 5
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure
    ports:
      - "8080:8080"
    environment:
      - Koreshield_API_KEY=${Koreshield_API_KEY}
    networks:
      - Koreshield

networks:
  Koreshield:
    driver: overlay

Deploy:

docker stack deploy -c docker-stack.yml Koreshield

Monitoring​

Prometheus Integration​

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

Log Aggregation​

services:
  Koreshield:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Best Practices​

Security​

# Use specific versions
FROM python:3.11.6-slim

# Run as non-root
USER 1000:1000

# Read-only root filesystem
docker run --read-only \
  --tmpfs /tmp \
  Koreshield/Koreshield:latest

Resource Limits​

docker run -d \
  --cpus="2" \
  --memory="4g" \
  --memory-swap="4g" \
  Koreshield/Koreshield:latest

Troubleshooting​

View Logs​

docker logs Koreshield
docker logs -f Koreshield  # Follow logs

Execute Commands​

docker exec -it Koreshield bash
docker exec Koreshield python -m Koreshield.cli status

Health Check​

curl http://localhost:8080/health