pull-config

Cron-based configuration management that pulls config files from the manager API. Installed on agent and manager containers. For deployment instructions, see Deploying Agents.

Architecture

Executable instance scripts in /etc/pull-config.d/ are run every minute by cron via run-parts. Each script sources environment variables, sets service-specific config, and calls the main pull-config binary.

pull-config/
├── bin/
│   └── pull-config          # Main script (called by instance scripts)
├── etc/
│   ├── cron.d/
│   │   └── pull-config      # Single cron entry: run-parts /etc/pull-config.d
│   └── pull-config.d/       # Executable instance scripts
│       ├── nginx
│       ├── dnsmasq-conf
│       ├── dnsmasq-dhcp-hosts
│       ├── dnsmasq-hosts
│       ├── dnsmasq-dhcp-opts
│       └── dnsmasq-servers
└── install.sh               # Copies scripts to /etc/

Environment Variables

Sourced from /etc/environment by each instance script. Set via container runtime (Docker ENV, Proxmox LXC config) — the base image's environment.sh service propagates them on boot.

Variable	Required	Description
SITE_ID	Yes	Numeric site ID from the manager
MANAGER_URL	Yes	Base URL of the manager (e.g., http://192.168.1.10:3000)
API_KEY	No	Bearer token for remote agents. Not needed on the manager (localhost is trusted).

The agent Dockerfile defaults to SITE_ID=1 and MANAGER_URL=http://localhost:3000 so the manager container works without configuration.

Instance Script Variables

Each instance script exports these before calling exec /opt/opensource-server/pull-config/bin/pull-config:

Required (must be exported)

Variable	Description
CONF_FILE	Target configuration file path
CONF_URL	URL to fetch configuration from

Optional

Variable	Description
TEST_COMMAND	Command to validate config before applying (e.g., nginx -t)
RELOAD_COMMAND	Custom command to reload the service
SERVICE_NAME	Service name for systemctl reload-or-restart fallback

Adding an Instance

Create an executable script in /etc/pull-config.d/:

#!/usr/bin/env bash

set -a; . /etc/environment; set +a

export CONF_FILE=/etc/myservice/config.conf
export CONF_URL=${MANAGER_URL}/sites/${SITE_ID}/myservice.conf
export TEST_COMMAND="myservice --validate-config"
export SERVICE_NAME="myservice"

exec /opt/opensource-server/pull-config/bin/pull-config

sudo chmod +x /etc/pull-config.d/myservice

The cron job picks it up automatically on the next run.

File Naming

run-parts only executes files matching: a-zA-Z0-9_- (no dots — use nginx not nginx.sh).

Behavior

• ETag caching — only downloads when the manager reports a change (HTTP 304)
• Validation — runs TEST_COMMAND before applying; rolls back on failure
• API key auth — sends Authorization: Bearer $API_KEY when API_KEY is set
• Reload — uses RELOAD_COMMAND if set, otherwise systemctl reload-or-restart $SERVICE_NAME