Upgrade

Production upgrades use the managed upgrader: back up data, select a target version, verify and synchronize release files, run migrations, and check every service. Do not reinitialize the deployment or delete Docker volumes.

1. Back up before upgrading

Before upgrading, complete one stopped full backup using Backup & Restore.

2. Run a standard upgrade

When the local scripts/upgrade.sh supports --version, run this from the existing asp-compose/ deployment directory:

./scripts/upgrade.sh --version <version>

Use the target GitHub Release version for <version> without the v prefix.

The upgrader changes the backend and frontend image tags in .env to the target version while preserving the current image repositories. It stops for manual handling when an image is pinned by digest or cannot be parsed safely.

3. Bootstrap an older deployment

First use a non-executing text check to see whether the local script supports managed upgrades:

grep -q -- '--version' ./scripts/upgrade.sh

If the command finds no match, download the standalone upgrader and checksum from the target Release:

version="<version>"
base_url="https://github.com/FunnyWolf/agentic-soc-platform/releases/download/v${version}"

curl -fL -O "${base_url}/asp-upgrade-${version}.sh"
curl -fL -O "${base_url}/asp-upgrade-${version}.sh.sha256"
sha256sum -c "asp-upgrade-${version}.sh.sha256" &&
  chmod +x "asp-upgrade-${version}.sh" &&
  ./asp-upgrade-${version}.sh --version "${version}" &&
  rm -f "asp-upgrade-${version}.sh" "asp-upgrade-${version}.sh.sha256"

This is a one-time step. After a successful upgrade, the local scripts/upgrade.sh is current and later releases use step 2.

This path works only for releases that include the standalone upgrader and SHA-256 file. Follow the one-time instructions in older release notes when those assets are absent.

4. What the upgrader manages

The upgrader downloads the target Release Compose package and .sha256, then verifies, backs up, and updates these release-managed files:

• compose.yaml
• scripts/
• .env.example
• README.md
• README.zh.md

It never overwrites deployment state or user content:

• .env
• compose.override.yaml
• custom/
• certs/
• logs/
• Docker named volumes

It then validates the Compose configuration, pulls images, runs database migrations, starts services, and runs doctor.sh against every official long-running service.

5. Customize Compose safely

init.sh and the managed upgrader create a compose.override.yaml containing explanatory comments and an empty services: {} mapping when it does not exist. This file is user-maintained and is never overwritten by upgrades.

Keep supported passwords, ports, and image settings in .env. Edit compose.override.yaml only for service-level additions such as volumes, environment variables, or command overrides:

services:
  asp-web:
    environment:
      EXAMPLE_SETTING: value

Do not edit the official compose.yaml directly; the next managed upgrade replaces it with the target Release version.

6. Failures and recovery

The upgrader stores the previous official files and .env under:

backups/upgrade-<version>-<timestamp>-<pid>/

• If download, SHA-256 verification, file replacement, Compose validation, or image pulling fails, the script restores the old files before any database migration is attempted.
• Automatic downgrade is disabled once database migration starts because old images may not support the new database schema. Migration, startup, or health-check failures leave the new files in place and print the backup path before stopping.

For failures after migration starts, inspect the command output and service logs, then follow the target release notes. Do not immediately restore old images.

7. Check after upgrading

The upgrader runs checks automatically. You can run them again:

docker compose ps
./scripts/doctor.sh

If a service is unhealthy, inspect its logs:

docker compose logs --tail=100 asp-web
docker compose logs --tail=100 asp-worker-dashboard-cache

Keep using the same asp-compose/ directory in production. The default Compose project name comes from the directory name; renaming it can change Docker named volume names and make existing data appear missing.

Next Steps

• Restart & Operations — Check service status, logs, and common restart commands after upgrading.
• Dashboard — Open the workspace and review the security operations overview.
• Case — Learn how analysts review evidence and drive response around Cases.