processmanager

Process Managers

This package provides process manager implementations for managing game server lifecycles. Each process manager implements the contracts.ProcessManager interface.

Available Process Managers

Metrics support

The Metrics(ctx, server) method returns Prometheus-style samples (see internal/app/metrics) that the daemon's metrics collector aggregates and forwards to the panel via gRPC.

Container-backed managers tag their metrics with {server_id, server_uuid, container}. The systemd manager tags its metrics with {server_id, server_uuid, service}.

The systemd manager reads metrics from systemctl show and relies on the CPUAccounting=yes, MemoryAccounting=yes, IOAccounting=yes, IPAccounting=yes and TasksAccounting=yes directives that the daemon writes into every generated unit file. Game servers running on units created before these directives existed will report zeros (and a suppressed CPU%) until the next start/restart regenerates the unit. Metrics are also suppressed for the first sample after each restart, since the cumulative CPU counter has no baseline yet.

PID-based stats for tmux / simple / winsw / shawl are tracked as a follow-up.

Configuration

Process manager is configured in the daemon configuration file:

process_manager:
  name: docker  # or: tmux, systemd, simple, winsw, shawl, podman
  config:
    # Process manager specific configuration
    image: "debian:bookworm-slim"

Docker Process Manager

The Docker process manager runs game servers inside Docker containers using the Docker SDK.

Features

• Container lifecycle management (create, start, stop, remove)
• Automatic image pulling
• Port mapping for game server ports
• Resource limits (memory, CPU)
• Volume mounting
• Custom installation scripts
• Log streaming
• Input sending via container attach

Configuration Priority

Configuration values are resolved in the following priority order:

1. Server Variables (server.Vars()) - Highest priority
2. GameMod Metadata (server.GameMod().Metadata)
3. Game Metadata (server.Game().Metadata)
4. ProcessManager Config (process_manager.config) - Lowest priority

Metadata Keys

Runtime Configuration

Installation Configuration

Note: If docker_installation_entrypoint is not set, the shell is auto-detected from the script's shebang line (e.g., #!/bin/ash → /bin/ash). Falls back to /bin/sh if no shebang is found.

Note: Installation runs as root by default because most scripts need root permissions to install packages (apt, yum, etc.). If your script doesn't need root, set docker_installation_user to match your server user. Remember to chown files to the server user at the end of your installation script if running as root.

Examples

Basic Game Configuration (Game Metadata)

{
  "docker_image": "gameap/srcds:latest",
  "docker_memory_limit": "4g",
  "docker_cpu_limit": "2.0"
}

Server-Specific Override (Server Variables)

{
  "docker_image": "gameap/csgo:latest",
  "docker_memory_limit": "8g",
  "docker_container_name": "csgo-competitive-server"
}

Installation Script Example

{
  "docker_installation_image": "ghcr.io/parkervcp/installers:alpine",
  "docker_installation_script": "#!/bin/ash\nset -e\napk add --no-cache curl\ncurl -sL https://example.com/install.sh | ash\n"
}

The shell is auto-detected from the shebang (#!/bin/ash). To override explicitly:

{
  "docker_installation_image": "ghcr.io/parkervcp/installers:alpine",
  "docker_installation_script": "...",
  "docker_installation_entrypoint": "ash"
}

Additional Volumes

JSON array format:

{
  "docker_volumes": "[\"/shared/maps:/server/maps:ro\", \"/shared/configs:/server/configs\"]"
}

Comma-separated format:

{
  "docker_volumes": "/shared/maps:/server/maps:ro,/shared/configs:/server/configs"
}

Capabilities and Privileged Mode

{
  "docker_capabilities": "NET_RAW,NET_ADMIN,SYS_NICE",
  "docker_privileged": "false"
}

Port Mapping

Ports are automatically mapped based on server configuration:

Container Lifecycle

Install:
  └─> If docker_installation_image && docker_installation_script:
      └─> Pull installation image
      └─> Create temp container with script
      └─> Mount server.WorkDir -> /mnt/server
      └─> Run container, wait for completion
      └─> Remove temp container
  └─> Else: Pull docker_image (optional)

Start:
  └─> Remove existing container (if any)
  └─> Pull image (if missing)
  └─> Create container
  └─> Start container

Stop:
  └─> Stop container (30s timeout)
  └─> Remove container

Status:
  └─> Inspect container
  └─> Return Running/NotRunning

GetOutput:
  └─> Get container logs (last 500 lines)

SendInput:
  └─> Attach to container stdin
  └─> Write input

Process Manager Config Options

process_manager:
  name: docker
  config:
    image: "debian:bookworm-slim"      # Default base image
    memory_limit: "2g"                  # Default memory limit
    cpu_limit: "1.0"                    # Default CPU limit
    host: "tcp://remote-docker:2376"   # Docker daemon address (DOCKER_HOST)
    cert_path: "/path/to/certs"        # TLS certificates directory (DOCKER_CERT_PATH)
    api_version: "1.41"                # Docker API version (DOCKER_API_VERSION)

Docker Connection Options

If none of these keys are set, the client falls back to client.FromEnv (reads from environment variables).

Podman Process Manager

The Podman process manager runs game servers inside Podman containers using the Podman REST API.

Features

• Compatible with Docker metadata keys (uses same docker_* prefix)
• Container lifecycle management
• Automatic image pulling
• Port mapping
• Resource limits
• Volume mounting
• Rootless container support

Prerequisites

Podman socket must be running:

# For rootless Podman
systemctl --user start podman.socket

# For root Podman
sudo systemctl start podman.socket

Configuration Priority

Same as Docker - see Configuration Priority above.

Metadata Keys

Podman uses the same metadata keys as Docker for compatibility:

Socket Configuration

process_manager:
  name: podman
  config:
    socket_path: "unix:///run/user/1000/podman/podman.sock"

Default socket paths:

• Rootless: unix:///run/user/{UID}/podman/podman.sock
• Root: unix:///run/podman/podman.sock

Examples

Basic Configuration

process_manager:
  name: podman
  config:
    image: "debian:bookworm-slim"

Game Metadata Example

{
  "docker_image": "gameap/minecraft:latest",
  "docker_memory_limit": "4g",
  "docker_cpu_limit": "2.0",
  "docker_dns": "8.8.8.8,1.1.1.1"
}

Comparison: Docker vs Podman

Error Handling

Both Docker and Podman process managers implement:

• Retry logic: Connection errors are retried with exponential backoff (100ms to 5s, max 3 retries)
• Graceful container removal: Containers are force-removed on stop/uninstall
• Image auto-pull: Missing images are automatically pulled on start
• Stop timeout: 30 seconds default timeout for graceful container stop

Troubleshooting

Docker

Connection refused

# Check Docker daemon is running
sudo systemctl status docker

# Check socket permissions
ls -la /var/run/docker.sock

Permission denied

# Add user to docker group
sudo usermod -aG docker $USER
# Re-login required

Podman

Socket not found

# Start Podman socket (rootless)
systemctl --user enable --now podman.socket

# Verify socket exists
ls -la /run/user/$(id -u)/podman/podman.sock

Connection refused

# Check Podman socket status
systemctl --user status podman.socket

# Test socket
curl --unix-socket /run/user/$(id -u)/podman/podman.sock http://d/v4.0.0/libpod/info