Skip to content

CONTAINER_CONFIG.md

Latest commit

 

History

History
263 lines (198 loc) · 5.53 KB

CONTAINER_CONFIG.md

File metadata and controls

263 lines (198 loc) · 5.53 KB

Container Configuration Guide

Overview

All container resource settings are now fully configurable through config.yaml.

Configuration Options

Basic Settings

container:
  enabled: true           # Enable/disable containerization
  mode: "native"          # "native" or "docker"
  base_path: "/var/pastebox/containers"  # Container storage path

Resource Limits

Control CPU, memory, and process limits per container:

container:
  limits:
    cpu_quota_micros: 100000    # CPU quota in microseconds
    cpu_period_micros: 100000   # CPU period in microseconds
    memory_mb: 512              # Memory limit in MB
    pids_limit: 100             # Max number of processes

CPU Configuration

  • cpu_quota_micros: How much CPU time the container gets per period
  • cpu_period_micros: The period length

Examples:

# 1 CPU (100% of one core)
cpu_quota_micros: 100000
cpu_period_micros: 100000

# 2 CPUs (200% = 2 cores)
cpu_quota_micros: 200000
cpu_period_micros: 100000

# 0.5 CPU (50% of one core)
cpu_quota_micros: 50000
cpu_period_micros: 100000

Memory Configuration

# 512 MB
memory_mb: 512

# 1 GB
memory_mb: 1024

# 2 GB
memory_mb: 2048

Process Limits

# Allow up to 100 processes
pids_limit: 100

# Allow up to 500 processes
pids_limit: 500

Namespace Configuration

Control which Linux namespaces are enabled:

container:
  namespaces:
    pid: true       # Process isolation
    mount: true     # Filesystem isolation
    network: true   # Network isolation
    uts: true       # Hostname isolation
    ipc: true       # IPC isolation
    user: false     # User namespace (requires special setup)

Namespace Descriptions:

  • pid: Isolates process IDs (container can't see host processes)
  • mount: Isolates mount points (container has own filesystem view)
  • network: Isolates network stack (container has own network)
  • uts: Isolates hostname (container can have different hostname)
  • ipc: Isolates inter-process communication
  • user: Maps user/group IDs (advanced, usually disabled)

Example Configurations

Development (Low Resources)

container:
  enabled: true
  mode: "native"
  limits:
    cpu_quota_micros: 50000    # 0.5 CPU
    cpu_period_micros: 100000
    memory_mb: 256             # 256 MB
    pids_limit: 50
  namespaces:
    pid: true
    mount: true
    network: false  # Disable for faster startup
    uts: false
    ipc: false
    user: false

Production (High Security)

container:
  enabled: true
  mode: "native"
  limits:
    cpu_quota_micros: 200000   # 2 CPUs
    cpu_period_micros: 100000
    memory_mb: 1024            # 1 GB
    pids_limit: 200
  namespaces:
    pid: true      # All enabled for maximum isolation
    mount: true
    network: true
    uts: true
    ipc: true
    user: false    # Still disabled (requires UID mapping)

High Performance

container:
  enabled: true
  mode: "native"
  limits:
    cpu_quota_micros: 400000   # 4 CPUs
    cpu_period_micros: 100000
    memory_mb: 2048            # 2 GB
    pids_limit: 500
  namespaces:
    pid: true
    mount: true
    network: true
    uts: true
    ipc: true
    user: false

Minimal Isolation (Testing)

container:
  enabled: false  # Disable containerization entirely
  # Falls back to simple process isolation

Resource Calculation

CPU

Formula: CPUs = cpu_quota_micros / cpu_period_micros

Examples:

  • 1 CPU: 100000 / 100000 = 1.0
  • 2 CPUs: 200000 / 100000 = 2.0
  • 0.5 CPU: 50000 / 100000 = 0.5

Memory

Direct conversion: memory_mb MB of RAM

Examples:

  • 512 MB: memory_mb: 512
  • 1 GB: memory_mb: 1024
  • 4 GB: memory_mb: 4096

Monitoring

Check resource usage:

# Via CLI
./bin/pasteboxctl status box-123

# Via API
curl http://localhost:8080/api/pastebox/box-123/status \
  -H "Authorization: Bearer <token>"

Troubleshooting

Container fails to start

Issue: failed to create container

Solutions:

  1. Check if running on Linux (containers require Linux)
  2. Verify /var/pastebox/containers exists and is writable
  3. Check if cgroups v2 is enabled: ls /sys/fs/cgroup/

Out of memory errors

Issue: Container killed by OOM

Solutions:

  1. Increase memory_mb in config
  2. Check application memory usage
  3. Monitor with: ./bin/pasteboxctl status box-123

CPU throttling

Issue: Container running slowly

Solutions:

  1. Increase cpu_quota_micros
  2. Check CPU usage in stats
  3. Consider increasing to 2+ CPUs for heavy workloads

Permission denied errors

Issue: Cannot create namespaces

Solutions:

  1. Run as root (required for namespaces)
  2. Disable problematic namespaces (e.g., user: false)
  3. Check kernel support: ls /proc/self/ns/

Best Practices

  1. Start Conservative: Begin with default settings
  2. Monitor First: Check actual resource usage before adjusting
  3. Scale Gradually: Increase limits incrementally
  4. Test Changes: Verify in development before production
  5. Document Limits: Note why specific limits were chosen

Platform Notes

Linux (Production)

  • ✅ Full support for all features
  • ✅ All namespaces available
  • ✅ Cgroups v2 recommended

macOS (Development)

  • ⚠️ Stubs only, no actual isolation
  • ⚠️ Config still validated
  • ⚠️ Use for development/testing only

See Also