Upgrade

Upgrade a self-hosted Vulnsy installation to a new release. Back up, download and extract the new offline package, run the installer's upgrade command, and check the health and version endpoints.

Each Vulnsy release is a new offline package, vulnsy-X.Y.Z-offline.tar.gz, with every image Vulnsy runs. The installer in the new package loads its images, replaces the Compose files, and restarts Vulnsy on the new version. Your configuration, databases and files stay where they are, and the new version applies any database changes itself when it starts. No internet access is needed.

Before you upgrade, read the release notes for every version between yours and the new one, and make any configuration changes they mention. To see which version you run:

sudo /opt/vulnsy/install.sh status

Back up

sudo /opt/vulnsy/install.sh backup

A backup is the only way back to the version you run now. See Backup & Restore.

Download and extract the new package

Download the new package and its .sha256 file from the link in your license email, copy them to the server, then:

sha256sum -c vulnsy-1.5.0-offline.tar.gz.sha256
tar xzf vulnsy-1.5.0-offline.tar.gz
cd vulnsy-1.5.0

Run the upgrade

From the new package directory:

sudo ./install.sh upgrade

The installer asks for confirmation, then:

Verifies every file of the package against SHA256SUMS.
Loads the new images.
Replaces docker-compose.yml, the files in docker/, .env.self-hosted.example and install.sh in /opt/vulnsy. It never changes .env, docker/Caddyfile, docker/certs/ or docker-compose.override.yml.
Sets VULNSY_VERSION in .env to the new version.
Recreates the containers whose image changed, waits until Vulnsy reports healthy, and prints the old and new versions.

Vulnsy is unavailable while the new app container starts. Before it serves requests, the new version applies schema changes to the databases and updates the Vulnsy library. Use --home if you installed somewhere other than /opt/vulnsy, and --yes to skip the confirmation.

Verify

curl -fsS https://reports.example.com/api/health
curl -fsS https://reports.example.com/api/version

/api/health returns HTTP 200 with "status":"ok", and /api/version reports the new version. sudo /opt/vulnsy/install.sh status shows the same, with the state of each container and the license.

After a successful upgrade you can delete the extracted package directory. The images of the previous version stay loaded; remove them with sudo docker image rm vulnsy/vulnsy:1.4.0 to free disk space.

Global library updates

Each release ships an updated global library (the shared finding templates, report templates, report styles, narratives, scoping templates and project types). Your own edits to these global items are never overwritten automatically. When an upgrade includes changes, the installer tells you how many items are new or updated and asks whether to import them:

This release ships global library updates: 12 new, 3 updated (findings, templates, styles, ...).
They were not applied automatically, so your own edits to global items are preserved.
Import the global library update now? [y/N]

Answer y to apply them (Vulnsy restarts to import), or import later at any time:

sudo /opt/vulnsy/install.sh import-globals

Importing overwrites your edits to those global items with the versions shipped in the release. Items you created yourself are left untouched. A brand-new installation always starts with the full library.

Health and Version Endpoints

Both endpoints are public. They need no sign-in and keep responding without a license, so you can use them for monitoring.

Endpoint	Returns
`GET /api/health`	HTTP 200 with `"status":"ok"` when the app can query all three databases. HTTP 503 with `"status":"degraded"` when it cannot, and the `checks` field shows which database failed. The container's healthcheck calls this endpoint.
`GET /api/version`	The running build. Unauthenticated callers get `version` and `edition`; a signed-in administrator also gets `sha` (the source commit) and `node` (the Node.js version).

Example responses:

{"status":"ok","version":"1.1.0","checks":{"controlPlane":"ok","shared":"ok","tenant":"ok"}}

{"version":"1.1.0","edition":"self-hosted"}

Downgrading

The installer refuses to upgrade to a package older than the installed version, and Vulnsy refuses to start an image older than the version recorded in its database.

To return to an earlier version, restore the backup that you took before upgrading, with the package of that earlier version: run sudo ./install.sh restore from the earlier package's directory. See Restore.

PostgreSQL, File Storage and Caddy

The package also contains the PostgreSQL, Silo (file storage) and Caddy images, at the versions Vulnsy is tested with. When a release updates one of them, install.sh upgrade loads the new image and recreates that container. You do not update them separately.

Release Notes

Each release comes with release notes, taken from the matching section of the Vulnsy changelog.

Upgrade

On this page