Quick Start
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:
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:Dockerfile
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"]
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
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:Dockerfile.optimized
# 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
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
Always use specific image versions in production to ensure reproducible deployments.
# 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
Set resource limits to prevent container resource exhaustion and ensure predictable performance.
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