Docker Deployment Guide¶

# Pull the latest production image
docker pull sodlinken/jairouter:latest

# Pull a specific version
docker pull sodlinken/jairouter:v1.0.0

# For Chinese users (using the Alibaba Cloud mirror)
docker pull registry.cn-hangzhou.aliyuncs.com/sodlinken/jairouter:latest

# Verify the image
docker images | grep sodlinken/jairouter

# Simplest way to run (JWT authentication enabled by default)
docker run -d \
  --name jairouter \
  -e SPRING_PROFILES_ACTIVE=dev \
  -e JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Simplest way to run (JWT authentication disabled)
docker run -d \
  --name jairouter \
  -e SPRING_PROFILES_ACTIVE=dev \
  -e JAIROUTER_SECURITY_JWT_ENABLED=false \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Verify deployment
curl http://localhost:8080/actuator/health

# Run with the configuration file mounted
docker run -d \
  --name jairouter \
  -e SPRING_PROFILES_ACTIVE=dev \
  -e JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" \
  -p 8080:8080 \
  -v $(pwd)/config:/app/config:ro \
  -v $(pwd)/logs:/app/logs \
  sodlinken/jairouter:latest

# Use the China-optimized build script
./scripts/docker-build-china.sh

# Or build manually
mvn clean package -Pchina
docker build -f Dockerfile.china -t sodlinken/jairouter:latest .

# Use the standard build script
./scripts/docker-build.sh

# Or build manually
mvn clean package
docker build -t sodlinken/jairouter:latest .

# Use the Dockerfile plugin
mvn clean package dockerfile:build -Pdocker

# Use the Jib plugin (no Docker required)
mvn clean package jib:dockerBuild -Pjib

# Build and push to the registry
mvn clean package jib:build -Pjib \
  -Djib.to.image=your-registry/sodlinken/jairouter:latest

# Build the development image
docker build -f Dockerfile.dev -t sodlinken/jairouter:dev .

# Build the production image
docker build -f Dockerfile -t sodlinken/jairouter:prod .

# Build the China-optimized image
docker build -f Dockerfile.china -t sodlinken/jairouter:china .

docker run -d \
  --name jairouter \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e PROD_ADMIN_API_KEY=adminkey \
  -e PROD_SERVICE_API_KEY=serviceaoi \
  -e PROD_READONLY_API_KEY=readonly \
  -e JAIROUTER_SECURITY_ENABLED=true \
  -e JAIROUTER_SECURITY_API_KEY_ENABLED=true \
  -e JAIROUTER_SECURITY_JWT_ENABLED=true \
  -e PROD_JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" \
  -e JAVA_OPTS="-Xms512m -Xmx1024m -XX:+UseG1GC -XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0"\
  -v $(pwd)/config:/app/config:ro \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/config-store:/app/config-store \
  --restart unless-stopped \
  --health-cmd="curl -f http://localhost:8080/actuator/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  --health-start-period=60s \
  sodlinken/jairouter:latest

docker run  \
  --name jairouter \
  -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e PROD_ADMIN_API_KEY=adminkey \
  -e PROD_SERVICE_API_KEY=serviceaoi \
  -e PROD_READONLY_API_KEY=readonly \
  -e JAIROUTER_SECURITY_ENABLED=true \
  -e JAIROUTER_SECURITY_API_KEY_ENABLED=true \
  -e JAIROUTER_SECURITY_JWT_ENABLED=true \
  -e PROD_JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" \
  -e JAVA_OPTS="-Xms512m -Xmx1024m -XX:+UseG1GC -XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0" \
  --restart unless-stopped \
  --health-cmd="curl -f http://localhost:8080/actuator/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  --health-start-period=60s \
  sodlinken/jairouter:latest

docker run -d \
  --name jairouter-dev \
  -p 8080:8080 \
  -p 5005:5005 \
  -e SPRING_PROFILES_ACTIVE=dev \
  -e JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" \
  -e JAVA_OPTS="-Xms256m -Xmx512m -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/src:/app/src:ro \
  sodlinken/jairouter:dev

# Windows PowerShell
.\scripts\docker-run.ps1 prod latest

# Linux/macOS Bash
./scripts/docker-run.sh prod latest

# Development environment
./scripts/docker-run.sh dev latest

version: '3.8'

services:
  jairouter:
    image: sodlinken/jairouter:latest
    container_name: jairouter
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - PROD_ADMIN_API_KEY=adminkey 
      - PROD_SERVICE_API_KEY=serviceaoi 
      - PROD_READONLY_API_KEY=readonly 
      - JAIROUTER_SECURITY_ENABLED=true 
      - JAIROUTER_SECURITY_API_KEY_ENABLED=true 
      - JAIROUTER_SECURITY_JWT_ENABLED=true 
      - PROD_JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" 
      - JAVA_OPTS=-Xms512m -Xmx1024m -XX:+UseG1GC
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
      - ./config-store:/app/config-store
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    networks:
      - jairouter-network

networks:
  jairouter-network:
    driver: bridge

version: '3.8'

services:
  jairouter:
    image: sodlinken/jairouter:latest
    container_name: jairouter
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - PROD_ADMIN_API_KEY=adminkey 
      - PROD_SERVICE_API_KEY=serviceaoi 
      - PROD_READONLY_API_KEY=readonly 
      - JAIROUTER_SECURITY_ENABLED=true 
      - JAIROUTER_SECURITY_API_KEY_ENABLED=true 
      - JAIROUTER_SECURITY_JWT_ENABLED=true 
      - PROD_JWT_SECRET="your-very-strong-jwt-secret-key-at-least-32-characters-long" 
      - JAVA_OPTS=-Xms512m -Xmx1024m -XX:+UseG1GC
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
    restart: unless-stopped
    networks:
      - monitoring
    depends_on:
      - prometheus

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'
    networks:
      - monitoring

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana_data:/var/lib/grafana
      - ./monitoring/grafana/dashboards:/etc/grafana/provisioning/dashboards:ro
      - ./monitoring/grafana/datasources:/etc/grafana/provisioning/datasources:ro
    networks:
      - monitoring

volumes:
  prometheus_data:
  grafana_data:

networks:
  monitoring:
    driver: bridge

version: '3.8'

services:
  jairouter-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: jairouter-dev
    ports:
      - "8080:8080"
      - "5005:5005"  # Debug port
    environment:
      - SPRING_PROFILES_ACTIVE=dev
      - JWT_SECRET=your-dev-jwt-secret
      - JAVA_OPTS=-Xms256m -Xmx512m -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
      - ./src:/app/src:ro  # Source mount (hot reload)
    networks:
      - dev-network

networks:
  dev-network:
    driver: bridge

# Start basic services
docker-compose up -d

# Start services with monitoring
docker-compose -f docker-compose.monitoring.yml up -d

# Start the development environment
docker-compose -f docker-compose.dev.yml up -d

# View service status
docker-compose ps

# View logs
docker-compose logs -f jairouter

# Stop services
docker-compose down

# Basic port mapping
-p 8080:8080    # Application port

# Development environment port mapping
-p 8080:8080    # Application port
-p 5005:5005    # Debug port

# Monitoring port mapping
-p 9090:9090    # Prometheus
-p 3000:3000    # Grafana

# Bridge network (default)
networks:
  - jairouter-network

# Host network
network_mode: host

# Custom network
networks:
  custom-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

# Docker runtime health check
docker run -d \
  --health-cmd="curl -f http://localhost:8080/actuator/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  --health-start-period=60s \
  sodlinken/jairouter:latest

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

# View health status
docker ps --format "table {{.Names}}\t{{.Status}}"

# View health check logs
docker inspect jairouter --format='{{json .State.Health}}'

# Manual health check
curl http://localhost:8080/actuator/health

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'jairouter'
    static_configs:
      - targets: ['jairouter:8080']
    metrics_path: '/actuator/prometheus'
    scrape_interval: 10s

{
  "dashboard": {
    "title": "JAiRouter Dashboard",
    "panels": [
      {
        "title": "Request Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(http_server_requests_total[5m])",
            "legendFormat": "{{method}} {{uri}}"
          }
        ]
      },
      {
        "title": "Response Time",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(http_server_requests_seconds_bucket[5m]))",
            "legendFormat": "95th percentile"
          }
        ]
      }
    ]
  }
}

# Start the complete monitoring stack
docker-compose -f docker-compose.monitoring.yml up -d

# Access the monitoring UI
# Prometheus: http://localhost:9090
# Grafana: http://localhost:3000 (admin/admin)

# Log configuration
logging:
  level:
    # Core component log levels
    org.unreal.modelrouter: INFO
    org.unreal.modelrouter.security: DEBUG
    org.unreal.modelrouter.tracing: DEBUG

    # Spring framework log levels
    org.springframework: WARN
    org.springframework.web: INFO
    org.springframework.security: INFO

    # Web client log levels
    org.springframework.web.reactive.function.client: DEBUG

  # Console log configuration
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{traceId}] %logger{36} - %msg%n"

  # File log configuration
  file:
    name: /app/logs/jairouter.log
    max-size: 100MB
    max-history: 30
    total-size-cap: 10GB

  # Logback configuration
  logback:
    rollingpolicy:
      max-file-size: 100MB
      max-history: 30
      total-size-cap: 10GB

# View real-time logs
docker logs -f jairouter

# View the most recent logs
docker logs --tail 100 jairouter

# View logs from a specific time
docker logs --since "2024-01-15T10:00:00" jairouter

# Export logs
docker logs jairouter > jairouter.log 2>&1

# View the log file inside the container
docker exec jairouter cat /app/logs/jairouter.log

# Configure logrotate
cat > /etc/logrotate.d/docker-jairouter << EOF
/var/lib/docker/containers/*/*-json.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 root root
}
EOF

# Log configuration in Docker Compose
version: '3.8'

services:
  jairouter:
    image: sodlinken/jairouter:latest
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"

# Structured log configuration
logging:
  level:
    org.unreal.modelrouter: INFO
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{traceId}] %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{traceId}] %logger{36} - %msg%n"

  file:
    name: /app/logs/jairouter.log

  # JSON format log configuration
  structured:
    enabled: true
    format: json
    fields:
      timestamp: "@timestamp"
      level: "level"
      logger: "logger"
      message: "message"
      thread: "thread"
      traceId: "traceId"
      spanId: "spanId"

# Structured log output example
# {
#   "@timestamp": "2024-01-15T10:00:00.123Z",
#   "level": "INFO",
#   "logger": "org.unreal.modelrouter.ModelRouterApplication",
#   "message": "Application started successfully",
#   "thread": "main",
#   "traceId": "abc123def456"
# }

services:
  jairouter:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '1.0'
          memory: 1G

# Use multi-stage builds to reduce image size
# Use .dockerignore to exclude unnecessary files
# Run as a non-root user
# Enable health checks

# Use a custom network
networks:
  jairouter-network:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: jairouter0
      com.docker.network.driver.mtu: 1500

# View container status
docker ps -a --filter "name=jairouter"

# View startup logs
docker logs jairouter

# Check port usage
netstat -tulpn | grep 8080

# Check whether the image exists
docker images | grep sodlinken/jairouter

# Run a manual health check
curl -v http://localhost:8080/actuator/health

# Inspect inside the container
docker exec -it jairouter sh

# View application logs
docker exec jairouter cat /app/logs/jairouter.log

# Check the configuration file mount
docker exec jairouter ls -la /app/config

# View the configuration file contents
docker exec jairouter cat /app/config/application.yml

# Validate the configuration file format
docker exec jairouter java -jar app.jar --spring.config.location=/app/config/application.yml --dry-run

# Enter the container for debugging
docker exec -it jairouter sh

# View process status
docker exec jairouter ps aux

# View network connections
docker exec jairouter netstat -tulpn

# View system resources
docker stats jairouter

# View container resource usage
docker stats --no-stream jairouter

# View detailed container information
docker inspect jairouter

# View image layer information
docker history sodlinken/jairouter:latest

# Run the container with a non-root user
docker run -d \
  --user 1001:1001 \
  --name jairouter \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Set a read-only file system (except for necessary directories)
docker run -d \
  --read-only \
  --tmpfs /tmp \
  --tmpfs /app/logs \
  --name jairouter \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Limit container capabilities
docker run -d \
  --cap-drop ALL \
  --cap-add NET_BIND_SERVICE \
  --name jairouter \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Set security options
docker run -d \
  --security-opt no-new-privileges:true \
  --security-opt seccomp=profile.json \
  --name jairouter \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Network security configuration in docker-compose.yml
version: '3.8'

services:
  jairouter:
    image: sodlinken/jairouter:latest
    container_name: jairouter
    ports:
      - "8080:8080"
    # Limit container network access
    networks:
      - jairouter-network
    # Set as an internal network with no external access
    networks:
      jairouter-network:
        internal: true

networks:
  jairouter-network:
    driver: bridge

# Use Docker secrets to manage sensitive information
echo "your-api-key" | docker secret create jairouter-api-key -

# Use secrets in swarm mode
docker service create \
  --name jairouter \
  --secret jairouter-api-key \
  -p 8080:8080 \
  sodlinken/jairouter:latest

# Use secrets in docker-compose
version: '3.8'

services:
  jairouter:
    image: sodlinken/jairouter:latest
    secrets:
      - jairouter-api-key
    environment:
      - API_KEY_FILE=/run/secrets/jairouter-api-key

secrets:
  jairouter-api-key:
    file: ./secrets/api-key.txt

# Security configuration
security:
  # API Key configuration
  api-key:
    enabled: true
    header: X-API-Key
    keys:
      - name: default
        value: your-api-key-here

  # JWT configuration
  jwt:
    enabled: true
    secret: your-jwt-secret-key
    algorithm: HS256
    expiration-minutes: 60
    issuer: jairouter
    accounts:
      - username: admin
        password: admin-password
        roles: [ADMIN, USER]
        enabled: true
      - username: user
        password: user-password
        roles: [USER]
        enabled: true

  # CORS configuration
  cors:
    allowed-origins: "*"
    allowed-methods: "*"
    allowed-headers: "*"
    allow-credentials: false

# HTTPS configuration
server:
  port: 8443
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: password
    key-store-type: PKCS12
    key-alias: jairouter