Skip to main content

Upgrades

This page covers how to upgrade Infracast across all deployment types.

SaaS Customers

If you're using app.infracast.io, upgrades are fully automatic — zero downtime, zero action required. You can check the current version at https://api.infracast.io/api/v1/version.

Checking the Current Version​

# API version
curl https://your-domain.com/api/v1/version

# Docker image tag
docker inspect ghcr.io/azgardtek/vulcan:latest \
  --format '{{index .Config.Labels "org.opencontainers.image.version"}}'

# Agent version
infracast-agent version

Database Migrations​

Infracast handles database schema migrations automatically on startup. When a new version starts, it checks for pending migrations and applies them before serving traffic.

  • Migrations are idempotent — safe to run multiple times
  • Migrations run forward only — rollback requires restoring a database snapshot
  • The migration lock prevents two instances from running migrations simultaneously
warning

Always create a database backup before upgrading, especially for major version bumps. See Backup & Restore.

Upgrading SaaS​

No action needed. Infracast SaaS is upgraded automatically:

  • Upgrades deploy during low-traffic windows
  • ECS rolling deployment ensures zero downtime
  • Your data is migrated automatically
  • Release notes are posted to infracast.io/changelog

Upgrading Docker (Self-Hosted)​

Step 1: Back Up the Database​

docker compose exec postgres pg_dump \
  -U vulcan -d vulcan -F c \
  > backup-before-upgrade-$(date +%Y%m%d).dump

Step 2: Pull New Images​

docker compose pull

Step 3: Apply the Upgrade​

# Rolling restart (API will briefly be unavailable if single instance)
docker compose up -d

Infracast will:

  1. Start the new container
  2. Run database migrations automatically
  3. Begin serving traffic

Step 4: Verify​

# Check health
curl http://localhost:8080/healthz

# Confirm new version
curl http://localhost:8080/api/v1/version

# Check for migration errors
docker compose logs vulcan-api | grep -i "migrat"

Upgrading to a Specific Version​

To pin to a specific version instead of latest:

docker-compose.yml
services:
  vulcan-api:
    image: ghcr.io/azgardtek/vulcan:1.5.0  # pin to specific version
docker compose pull
docker compose up -d

Upgrading ECS / Terraform​

Step 1: Back Up RDS​

aws rds create-db-snapshot \
  --db-instance-identifier vulcan-prod \
  --db-snapshot-identifier vulcan-pre-upgrade-$(date +%Y%m%d)

Step 2: Update Image Tag​

Update your Terraform variable or ECS task definition to reference the new image:

terraform.tfvars
vulcan_image_tag = "1.5.0"  # or "latest"

Step 3: Apply with Terraform​

cd terraform/environments/vulcan-prod
terraform plan -out=upgrade.tfplan
terraform apply upgrade.tfplan

Terraform updates the ECS task definition and triggers a rolling deployment:

  1. New task starts with the updated image
  2. Migrations run on startup
  3. Health check passes → task registered with ALB
  4. Old task drained and stopped

Step 4: Force Deployment Without Terraform (Quick Method)​

# Force new deployment (pulls latest image if using :latest tag)
aws ecs update-service \
  --cluster vulcan-prod-cluster \
  --service vulcan-prod-service \
  --force-new-deployment

# Monitor rollout
aws ecs wait services-stable \
  --cluster vulcan-prod-cluster \
  --services vulcan-prod-service

Step 5: Verify​

# Check service is stable
aws ecs describe-services \
  --cluster vulcan-prod-cluster \
  --services vulcan-prod-service \
  --query "services[0].{Status:status,Running:runningCount,Desired:desiredCount}"

# Verify API health and version
curl https://your-domain.com/healthz
curl https://your-domain.com/api/v1/version

Upgrading Agents​

Agents should be upgraded separately from the server. Infracast maintains backward compatibility for at least 2 major versions.

Linux (Systemd)​

# Re-run the installer (upgrades in place)
curl -fsSL https://get.infracast.io/agent | sudo bash -s -- \
  --server https://api.infracast.io \
  --upgrade

# Verify
systemctl status infracast-agent
infracast-agent version

Windows​

# Download new installer
Invoke-WebRequest -Uri "https://releases.infracast.io/agent/latest/infracast-agent-windows-amd64.msi" `
  -OutFile "infracast-agent.msi"

# Install (upgrades existing service, preserves config)
msiexec /i infracast-agent.msi /quiet

# Verify
Get-Service InfracastAgent

Mass Upgrade with Ansible​

- name: Upgrade Infracast Agent
  hosts: all
  tasks:
    - name: Download latest agent
      get_url:
        url: "https://releases.infracast.io/agent/latest/infracast-agent-linux-amd64"
        dest: /usr/local/bin/infracast-agent
        mode: '0755'
      register: agent_binary

    - name: Restart agent if binary changed
      systemd:
        name: infracast-agent
        state: restarted
      when: agent_binary.changed

Rollback Procedures​

Docker Rollback​

# Pin to previous version
docker compose down
# Edit docker-compose.yml: change image tag to previous version
docker compose up -d

ECS Rollback​

Option 1 — ECS console: Click Update Service → Force new deployment with the previous task definition revision.

Option 2 — CLI:

# List recent task definitions
aws ecs list-task-definitions --family-prefix vulcan-prod --sort DESC

# Roll back to previous revision
aws ecs update-service \
  --cluster vulcan-prod-cluster \
  --service vulcan-prod-service \
  --task-definition vulcan-prod:42  # previous revision number

Database Rollback​

If a migration introduced a problem:

# Restore from pre-upgrade snapshot
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier vulcan-prod-rollback \
  --db-snapshot-identifier vulcan-pre-upgrade-20260416

# Update DATABASE_URL to point to restored instance
# Redeploy previous API version
danger

Database rollback is destructive — all data written after the snapshot is lost. Only perform this if the migration itself caused data corruption.

Upgrade Checklist​

Use this checklist before and after every upgrade:

Before:

  • Read release notes at infracast.io/changelog
  • Create database backup / RDS snapshot
  • Note current version (/api/v1/version)
  • Verify health: curl /healthz returns status: ok
  • Schedule during low-traffic window (self-hosted)

After:

  • Verify health: curl /healthz returns status: ok
  • Confirm new version: curl /api/v1/version
  • Check logs for migration errors: grep -i migrat
  • Run a discovery job and verify it completes successfully
  • Delete pre-upgrade snapshot after 48h (or keep per policy)