Configuration

Configuration

strut uses a layered configuration system: project-level settings in strut.conf, per-stack settings in stack directories, and per-environment secrets in dotenv files.

strut.conf

Project-level settings at the root of your project:

# Container registry: ghcr | dockerhub | ecr | none
REGISTRY_TYPE=ghcr

# Default GitHub/registry organization
DEFAULT_ORG=my-org

# Default git branch for VPS repo sync
DEFAULT_BRANCH=main

# Reverse proxy: nginx | caddy
REVERSE_PROXY=nginx

# Number of deploy rollback snapshots to keep
ROLLBACK_RETENTION=5

# Run config validation before every deploy (default: true)
PRE_DEPLOY_VALIDATE=true

# Run custom hooks from stacks/<stack>/hooks/pre-deploy.sh (default: true)
PRE_DEPLOY_HOOKS=true

# Deploy mode: standard (in-place) or blue-green (zero-downtime swap, since v0.20.0)
DEPLOY_MODE=standard

# Blue-green: seconds to wait for new color's health checks (default: 30)
BLUE_GREEN_HEALTH_TIMEOUT=30

# Blue-green: seconds to drain old color before stopping (default: 60)
BLUE_GREEN_DRAIN=60

# Blue-green: optional hook file defining bluegreen_proxy_swap()
# BLUE_GREEN_PROXY_HOOK=/path/to/hooks/bluegreen_proxy_swap.sh

# Banner text in deploy/release output
BANNER_TEXT=my-project

Created by strut init and read by lib/config.sh on every invocation.

Environment Files

The --env flag maps to dotenv files at the project root:

Flag	File	Use
--env prod	.prod.env	Production secrets
--env staging	.staging.env	Staging secrets
--env local	.local.env	Local development
(none)	.env	Default fallback

Required Variables

Every env file should include:

Variable	Purpose
VPS_HOST	SSH target IP or hostname
VPS_USER	SSH user (default: ubuntu)
VPS_DEPLOY_DIR	Path to strut installation on VPS
GH_PAT	GitHub Personal Access Token for private images
COMPOSE_PROJECT_NAME	Docker Compose project name

Optional Variables

Variable	Purpose
VPS_SUDO	Set to true if Docker requires sudo on VPS
SSH_KEY	Path to SSH private key
SSH_PORT	Custom SSH port (default: 22)

Per-Stack Configuration

Each stack under stacks/<name>/ can have these config files:

services.conf

Drives dynamic health checking and service discovery:

# Application services — <NAME>_PORT triggers HTTP health check
API_PORT=8000
API_HEALTH_PATH=/health

WORKER_PORT=8001

# Database flags — triggers database-specific probes
DB_POSTGRES=true
DB_REDIS=true
DB_NEO4J=true

required_vars

Plain text list of env var names that must be set before deploy:

DATABASE_URL
REDIS_URL
API_SECRET_KEY
GH_PAT

Validated by validate_env_file before deployment. Optional — if the file doesn't exist, validation is skipped.

volume.conf

Volume path mappings and ownership:

# volume_name:host_path:container_path:owner
postgres_data:/var/lib/postgresql/data:/var/lib/postgresql/data:999:999
uploads:/app/uploads:/app/uploads:1000:1000

repos.conf

GitHub repositories associated with this stack (used by key management):

my-org/my-service
my-org/my-agent
my-org/my-ops

backup.conf

Backup schedule and retention settings:

BACKUP_POSTGRES=true
BACKUP_SCHEDULE_POSTGRES="0 2 * * *"   # 02:00 UTC daily
BACKUP_RETAIN_DAYS=30
BACKUP_RETAIN_COUNT=10

BACKUP_NEO4J=true
BACKUP_SCHEDULE_NEO4J="0 3 * * *"

# SQLite (for stacks using Docker volumes)
BACKUP_SQLITE=true
BACKUP_SQLITE_USE_DOCKER=true

.drift-ignore

Files that legitimately differ at runtime (excluded from drift detection):

*.log
*.pid
.env
.env.local
docker-compose.override.yml
nginx/conf.d/ssl.conf
tmp/*
cache/*

anonymize.conf

PII anonymization rules for sync-db --anonymize. See Data Anonymization for details.

users.email=fake_email
users.name=fake_name
users.phone=null
payments.card_number=mask

Config Loading Order

1. strut entrypoint resolves STRUT_HOME
2. find_project_root() walks up from $PWD to find strut.conf
3. load_strut_config() reads strut.conf and applies defaults
4. Per-command: resolve_env_file() locates the env file based on --env flag
5. Per-command: stack-specific configs (services.conf, etc.) are read as needed