Deployment

Upgrading to teams

Converting an existing installation into its first team, and rolling back.

An installation from before teams is upgraded by converting a copy of its database into the first team. The existing database is never changed, so rolling back means pointing ScanSuite at it again.

What the conversion does

Creates one team and gives it every product, scan, finding, credential, asset, rule and schedule.
Makes every user a member of that team: former administrators become team admins, other users operators. Everyone keeps their password.
Moves the integration settings (DefectDojo, scanners, notifications, repository) into the team.
Moves installation-wide settings to the platform: the AI configuration becomes the system AI default, which the team uses, and the Nessus runs limit becomes the shared Nessus capacity.
Turns the old scan targets whitelist into the team's target policies.
Checks the result table by table against the copy it started from.

Rows that point at data that no longer exists, such as records of long-deleted scans, are set aside in an archive table rather than deleted, and the check accounts for them.

Before you start

What	Details
Images	The updated ScanSuite images, installed with install.
Encryption keys	SCANSUITE_WRAPPING_KEYS and PLATFORM_WRAPPING_KEYS, each a JSON object of a key name and a base64-encoded 32-byte key, with SCANSUITE_ACTIVE_WRAPPING_KEY and PLATFORM_ACTIVE_WRAPPING_KEY naming the key in use. Back them up outside the server: without them, stored integration passwords and AI keys cannot be read.
Two database accounts	The existing owner account for upgrades (PS_MIGRATION_USER, PS_MIGRATION_PASSWORD), and a new restricted account for the application (PS_DATABASE_USER, PS_DATABASE_PASSWORD) — the upgrade creates it.
Team name	A short name for the team (for example appsec), set as LEGACY_TEAM_SLUG, and who should be its admins.
Disk space	Room for a second copy of the database and a compressed dump.

Keep a copy of the current .env as env.before-upgrade; it is your rollback configuration. Then add the new settings to .env. Leave single sign-on off during the upgrade.

Upgrading

Stop ScanSuite

Shell

docker compose stop web worker worker_admin worker_poc celery_beat ai_docs

02
Dump the current database
The script refuses to run while anything else is connected, and checks that nothing changed during the dump.
Shell
```
scripts/scansuite-dump.sh --env-file env.before-upgrade --pg-container scansuite-gui-postgres-1 --output ./upgrade-dump
```

Convert it into a new database

Continue only after VERIFY: OK and AI-CHECK: OK. If only the AI check fails, you can continue and fix the AI key afterwards.

Shell

scripts/scansuite-migrate.sh --dump ./upgrade-dump --env-file .env --pg-container scansuite-gui-postgres-1 --target-dbname scansuite_teams --create-database --team-slug appsec --team-name "AppSec" --team-admin admin --check-ai --yes

04
Point ScanSuite at the new database
In .env, set PS_DATABASE_NAME=scansuite_teams and LEGACY_TEAM_SLUG to the team name.
05
Start ScanSuite
The upgrade job runs first; the application refuses to start until the database is current.
Shell
```
docker compose up -d
```

Check the installation

Shell

docker compose run --rm migrate python -m database.cutover monitor

Then sign in as a team admin and check that products, history, findings, assets and credentials look as before, that Team integrations shows your integrations, and that a small test scan runs. A local test of the upgrade took seconds for a small database; test on a copy of your own to size the maintenance window.

Rolling back

Until the new database has taken real work, restore the saved .env and start the previous version: the old database is exactly as it was. After that, anything done since the upgrade exists only in the new database, so prefer fixing forward.

Never roll back once a second team exists. The previous version does not know about teams and would show every team's data to everyone.

After the upgrade

Add people and manage accounts on the team's Members page: Members and accounts.
Review the target policies converted from the old whitelist: Teams and roles.
Set up single sign-on when you are ready: Single sign-on.
To add more teams, deploy the platform console: Platform administration.

Last reviewed 2026-09-19