Environment Lifecycle

Day-to-day tasks for creating, deploying, updating, stopping, and deleting environments through Jenkins jobs.

Templates

  • Location: shared-library/resources/templates/<service>/

  • Contents:

    • <service>.yaml — Docker Compose service definition.

    • .env — default variables for the service.

    • configs/ — optional extra files mounted into containers.

  • Dependencies: optional dependencies.yaml auto-generates depends_on relationships.

Create an Environment

  1. Jenkins → QA-Environments/Create-Environment.

  2. First run: click Build Now to prime parameters, then Build with Parameters.

  3. Parameters:

    • Environment name: auto (generates friendly slug) or custom.

    • TTL: e.g., 1w.

    • Services: choose one or more templates.

    • Variables: override defaults as needed.

  4. Result: rendered artifacts under /var/jenkins_home/qa-data/envs/<env>/:

    • docker-compose.yml

    • .env

    • <service>.env

    • meta.json (services, status, ttl, created_by, timestamps)

Deploy to an Agent

  1. Jenkins → QA-Environments/Deploy-Environment.

  2. Select target environment; agent label is auto-detected from meta.json when available.

  3. Pipeline stashes files from master, unstashes on the agent, and runs docker compose up -d.

  4. meta.json is updated with runner and deployment status.

Update or Reconfigure

  1. Edit parameters or templates, then run QA-Environments/Update-Environment.

  2. Pipeline creates a backup docker-compose.yml.backup-* on the agent.

  3. Re-renders templates, reapplies Compose changes, and updates metadata.

Stop vs Delete

  • Stop: QA-Environments/Stop-Environment — stops containers but retains files and volumes.

  • Delete: QA-Environments/Delete-Environment — removes containers, network, volumes, and files; use with caution.

TTL and Cleanup

  • TTL is stored in meta.json per environment.

  • Cleanup jobs scan for expired TTL and remove corresponding environments to free resources.

  • @tmp Jenkins workspaces are automatically filtered; leftover temp dirs can be pruned with utils.cleanupTempEnvDirs().

Backup and Restore

  • Before updates, Compose files are backed up on the agent as docker-compose.yml.backup-*.

  • To restore manually:

    cd /opt/qa-envs/<env>/
cp docker-compose.yml.backup-<ts> docker-compose.yml
docker compose up -d

Health Checks

  • Compose healthchecks defined in templates are honored.

  • If containers show unhealthy, increase interval, timeout, and start_period, or fix commands (use CMD-SHELL for env expansion).

Locking

  • Jobs use locks to prevent concurrent operations on the same environment (lock(resource: "env-<name>")).

  • Avoid manual interventions that bypass locks; use provided jobs instead.