Upgrading

Upgrades install a newer tagged release on the existing installation. Your database, keys and files stay where they are.

Before you upgrade

1. Read the changelog for the target release, especially notes about required steps.
2. Check your license (licensed installations only). Under System → License, compare your “updates until” date with the release date of the new version. If the new version was released after your update period ended, the installation falls back to the free edition until you renew. Existing users keep working either way. See Updates and renewals.
3. Take a backup under System → Operations and copy it off the host. Keep your key copy current.

Docker Compose

In .env, change only the version:

VAULTIGEN_IMAGE_TAG=1.1.0

Then download the new images, stop the old application processes and start the new version:

cd ~/vaultigen
docker compose pull && docker compose stop web worker scheduler && docker compose up -d --wait

The database keeps running. The one-off migrate service checks the installation and its keys, takes and verifies a backup if migrations are pending, applies them once, and only then lets web, worker and scheduler start. A failed backup or migration keeps the application stopped; read docker compose logs --tail=100 migrate, fix the cause and run docker compose up -d --wait again. Do not bypass the migrate service.

Keep the stop step: start-up order alone does not stop old web requests and queue jobs before the migration. Long imports, backups and rotations finish first, so stopping the worker can take a while.

You normally keep the same compose.yaml. Download the new release’s file only when its release notes say so. Updates never generate keys or delete anything in data/. The bundled database stays on PostgreSQL 18; changing VAULTIGEN_IMAGE_TAG never upgrades it, and a future major upgrade of the database will come with its own instructions. Do not change the database image yourself.

After the update:

• docker compose ps shows database, web, worker and scheduler as healthy.
• You can sign in and open an existing entry and attachment.
• System → Installation status is green, including License.
• An invitation or test email arrives.
• docker compose exec web php artisan vaultigen:backup completes.

Rolling back on Docker Compose

A schema change can prevent simply going back to the previous image. Roll back by restoring the backup taken before the update with the previous release; everything changed since that backup is lost:

docker compose stop web worker scheduler
nano .env    # set VAULTIGEN_IMAGE_TAG back to the previous release
docker compose run --rm --no-deps setup restore /backups/BACKUP_ID
docker compose up -d --wait

Use the set with trigger migration in System → Operations, or a backup you took yourself. The restore replaces every table, so tables added by the newer release do not remain. The keys in data/keys/ stay unchanged.

Manual installation

cd /var/www/vaultigen

php artisan down
git fetch --tags
git checkout v1.1.0   # the new release

composer install --no-dev --optimize-autoloader
npm ci
npm run build

php artisan migrate --force
php artisan optimize:clear
php artisan up

sudo systemctl restart vaultigen-queue vaultigen-scheduler

Restart PHP-FPM as well if you use OPcache with timestamp validation turned off.

After the upgrade

• Open System → Installation status and check that every item is green, including the License check.
• Sign in as an ordinary user, open a vault and reveal an entry.

Rules that never change

• Never run key:generate on an existing installation. APP_KEY protects stored authentication data.
• Never run vaultigen:initialize again or replace installation.json or kek.json. Existing data depends on the original values.
• Do not skip migrations. Run php artisan migrate --force after every code update. On Docker Compose, the migrate service does this for you.
• On Docker Compose, never run setup to repair an existing installation, and never delete or regenerate anything in data/keys/.

Rolling back a manual installation

If a release causes problems, check out the previous tag and rebuild. If the new release ran migrations that the old code cannot handle, restore the backup you took before the upgrade. See Restore.