Agent Configuration

The agent is configured via a YAML file (default: /etc/jokowipe/agent.yaml) and/or environment variables.

Full Configuration Reference

# /etc/jokowipe/agent.yaml

agent:
  name: "my-db-server"                  # Display name in the dashboard
  server_url: "https://api.jokowipe.id" # Control plane URL
  token: "${JOKOWIPE_AGENT_TOKEN}"       # Agent token (use env var)
  heartbeat_interval: 30s               # How often to send heartbeat (default: 30s)
  poll_interval: 10s                    # How often to poll for new jobs (default: 10s)
  log_level: info                       # debug, info, warn, error
  log_format: json                      # json or text
  temp_dir: /var/tmp/jokowipe           # Temp directory for backup files
  max_concurrent_jobs: 2                # Max parallel backup jobs (default: 1)

database:
  # Default database — used if no database is specified in the job
  url: "postgres://user:pass@localhost:5432/mydb"
  # Additional named databases
  databases:
    analytics:
      url: "postgres://user:pass@localhost:5432/analytics"
    mysql_app:
      url: "mysql://user:pass@localhost:3306/app"

storage:
  # Default storage target
  type: s3                              # s3, gcs, azure, local
  s3:
    bucket: "my-backups"
    region: "us-east-1"
    prefix: "jokowipe/"
    access_key_id: "${AWS_ACCESS_KEY_ID}"
    secret_access_key: "${AWS_SECRET_ACCESS_KEY}"
    storage_class: STANDARD_IA
    server_side_encryption: AES256
    path_style: false
    skip_tls_verify: false
    upload_part_size_mb: 64             # Multipart upload part size (default: 64 MB)
    upload_concurrency: 4              # Parallel upload parts (default: 4)

hooks:
  # Shell scripts run before/after each backup job
  pre_backup: "/opt/scripts/pre-backup.sh"
  post_backup: "/opt/scripts/post-backup.sh"
  on_failure: "/opt/scripts/notify-failure.sh"

tls:
  # Custom CA certificate (for self-hosted API)
  ca_cert: "/etc/jokowipe/ca.pem"
  # Client certificate (for mutual TLS)
  client_cert: "/etc/jokowipe/client.pem"
  client_key: "/etc/jokowipe/client-key.pem"
  insecure_skip_verify: false          # Never set to true in production

metrics:
  enabled: true
  port: 9090                           # Prometheus metrics endpoint
  path: /metrics

Environment Variables

All configuration values can be set as environment variables. The format is: JOKOWIPE_<SECTION>_<KEY> (uppercase, underscores for nested keys).

Environment Variable	Equivalent Config Key	Description
JOKOWIPE_AGENT_TOKEN	agent.token	Agent authentication token
JOKOWIPE_AGENT_NAME	agent.name	Agent display name
JOKOWIPE_SERVER_URL	agent.server_url	Control plane URL
JOKOWIPE_LOG_LEVEL	agent.log_level	Log level
JOKOWIPE_DATABASE_URL	database.url	Default database URL
JOKOWIPE_STORAGE_TYPE	storage.type	Storage provider type
AWS_ACCESS_KEY_ID	(referenced in config)	AWS access key
AWS_SECRET_ACCESS_KEY	(referenced in config)	AWS secret key

Configuration Precedence

Configuration values are resolved in this order (highest priority first):

1. Command-line flags (--token, --server-url, etc.)
2. Environment variables
3. Config file
4. Defaults

Config File Location

The agent looks for config in these locations (in order):

1. Path specified by --config flag
2. /etc/jokowipe/agent.yaml
3. $HOME/.jokowipe/agent.yaml
4. ./agent.yaml (current directory)

# Use a custom config file location
jokowipe-agent start --config /opt/myconfig/agent.yaml

Referencing Environment Variables in Config

Use ${VAR_NAME} syntax to reference environment variables inside the YAML config:

agent:
  token: "${JOKOWIPE_AGENT_TOKEN}"
storage:
  s3:
    access_key_id: "${AWS_ACCESS_KEY_ID}"
    secret_access_key: "${AWS_SECRET_ACCESS_KEY}"

The agent resolves these at startup. If the referenced variable is not set, the agent fails to start with a clear error message.

Validating Configuration

jokowipe-agent config validate
# ✓ Config file: /etc/jokowipe/agent.yaml
# ✓ Token: valid format
# ✓ Server URL: reachable
# ✓ Storage: S3 bucket accessible
# ✓ Pre-backup hook: /opt/scripts/pre-backup.sh (executable)

Multiple Agent Instances

To run multiple agents on the same machine (e.g., for different databases), use separate config files and systemd service instances:

# /etc/systemd/system/jokowipe-agent@.service
[Service]
ExecStart=/usr/local/bin/jokowipe-agent start --config /etc/jokowipe/%i.yaml

Then enable instances:

sudo systemctl enable --now jokowipe-agent@postgres
sudo systemctl enable --now jokowipe-agent@mysql