Skip to main content

​
Configuration

systemg uses YAML files to define services and their relationships.

​
Complete example

version: "1"
env:
  vars:
    APP_ENV: "production"
services:
  postgres:
    command: "postgres -D /var/lib/postgresql/data"
    restart_policy: "always"
  redis:
    command: "redis-server /etc/redis/redis.conf"
    restart_policy: "always"
  api:
    command: >
      gunicorn app:application
      --bind 0.0.0.0:8000
    env:
      file: "/etc/myapp/production.env"
      vars:
        PORT: "8000"
        DATABASE_URL: "postgres://localhost/myapp"
    depends_on:
      - postgres
      - redis
    restart_policy: "always"
    backoff: "10s"
    deployment:
      strategy: "rolling"
      pre_start: "python manage.py migrate"
      health_check:
        url: "http://localhost:8000/health"
    hooks:
      on_start:
        success:
          command: "echo 'API started'"
      on_stop:
        error:
          command: "curl --request POST https://alerts.example.com/api/crash"
  worker:
    command: >
      celery -A tasks worker
      --loglevel=info
    depends_on:
      - redis
    restart_policy: "on-failure"
    max_restarts: 5
  backup:
    command: >
      pg_dump mydb >
      /backups/db-$(date +%Y%m%d).sql
    cron: "0 2 * * *"

​
Configuration sections

​
version

Required. Specifies the configuration schema version. 
version: "1"

​
env

Optional environment variables shared by all services. 
env:
  vars:
    LOG_LEVEL: "info"
    APP_ENV: "production"
  file: "/etc/myapp/common.env"

​
services

Required. Defines the services to manage. 
services:
  web:
    command: "python app.py"

​
Service configuration

​
command

Required. The command to execute. 
services:
  web:
    command: "python app.py"

​
depends_on

Services that must start before this one. 
services:
  api:
    command: "python app.py"
    depends_on:
      - postgres
      - redis

​
env

Service-specific environment configuration. 
services:
  api:
    command: "python app.py"
    env:
      vars:
        PORT: "8000"
        DATABASE_URL: "postgres://localhost/myapp"
      file: "/etc/myapp/production.env"

​
restart_policy

Control how services recover from crashes. 
services:
  api:
    command: "python app.py"
    restart_policy: "always"
    backoff: "5s"
    max_restarts: 10
Policies:
  • always - Restart on any exit
  • on-failure - Restart only on non-zero exit codes
  • never - Don’t restart

​
hooks

Run commands when services start or stop. 
services:
  api:
    command: "python app.py"
    hooks:
      on_start:
        success:
          command: "curl --request POST https://status.example.com/api/up"
        error:
          command: "curl --request POST https://status.example.com/api/down"
      on_stop:
        error:
          command: "curl --request POST https://alerts.example.com/crash"

​
health_check

Verify services are ready before marking them healthy. 
services:
  api:
    command: "python app.py"
    health_check:
      command: "curl --fail http://localhost:8000/health"
      interval: "10s"
      timeout: "5s"
      retries: 3

​
cron

Run services on a schedule instead of continuously. 
services:
  backup:
    command: >
      pg_dump mydb >
      /backups/db-$(date +%Y%m%d).sql
    cron: "0 2 * * *"

​
deployment

Control how services update during restarts. 
services:
  api:
    command: "python app.py"
    deployment:
      strategy: "rolling"
      pre_start: "python manage.py migrate"
      health_check:
        url: "http://localhost:8000/health"
        timeout: "30s"
      grace_period: "5s"
      blue_green:
        env_var: "PORT"
        slots: ["8000", "8001"]
        candidate_health_check_url: "http://127.0.0.1:{slot}/health"
        switch_command: "/usr/local/bin/switch-upstream {candidate_slot}"
        switch_verify_url: "http://localhost:8000/health"
        state_path: ".state/api-slot.json"
Rolling deployments start the new instance, wait for health checks, then stop the old instance. For single-host zero-downtime with fixed ports, use blue_green so traffic can be switched between two slots.

​
Field reference

​
Service fields

Primary keys available on each service definition.
FieldTypeDescription
commandstringCommand to execute (required)
depends_onarrayServices that must start first
envobjectEnvironment configuration
restart_policystringalways, on-failure, or never
backoffstringTime between restart attempts
max_restartsnumberMaximum restart attempts
hooksobjectLifecycle event handlers
health_checkobjectService readiness probe
cronstringCron schedule expression
deploymentobjectUpdate strategy configuration

​
Environment object

Environment sources and inline overrides merged into the service process environment.
FieldTypeDescription
varsobjectKey-value environment variables
filestringPath to env file

​
Hooks object

Lifecycle callbacks you can trigger on service start/stop/restart outcomes.
FieldTypeDescription
on_startobjectCommands for start events
on_stopobjectCommands for stop events
on_restartobjectCommands for restart events
Each hook has success and error handlers with:
  • command - Command to execute
  • timeout - Maximum execution time

​
Health check object

Probe configuration used to determine readiness/health during deployment workflows.
FieldTypeDescription
commandstringCheck command
urlstringHTTP endpoint (alternative to command)
intervalstringTime between checks
timeoutstringCheck timeout
retriesnumberAttempts before marking unhealthy

​
Deployment object

Controls how restarts are performed and what validation happens before cutover.
FieldTypeDescription
strategystringrolling or immediate
pre_startstringCommand to run before starting
health_checkobjectHealth check configuration
grace_periodstringTime before stopping old instance
blue_greenobjectSingle-host blue/green rollout settings

​
Blue/green deployment object

Single-host zero-downtime options for alternating between two rollout slots (typically ports).
FieldTypeDescription
env_varstringEnv var injected with slot value (PORT default)
slotsarrayExactly two slot values to alternate between
switch_commandstringCommand to switch traffic to candidate slot
candidate_health_check_urlstringCandidate health probe URL template ({slot} supported)
switch_verify_urlstringOptional post-switch verify URL
state_pathstringOptional persisted active-slot state file path