PIES Studio 1.7 · Documentation

Upgrading PIES Studio

How to move a running installation to a new release, what to do first, and how to get back if you need to. For a first-time install see the installation guide.

Your data lives in Docker volumes, separate from the images. Upgrading replaces the images; it does not touch the volumes. That is what makes both the upgrade and the rollback straightforward — and it is also why the backup below matters: the volumes are the only copy.

Before you start

Pin the version you are on. If PIES_VERSION in your .env says latest, set it to the release you are actually running before you change anything. Rolling back to "latest" is not a rollback.

Back up the volumes. Stop the platform first so the databases are not written to mid-copy:

docker compose stop

# Compose prefixes volume names with the project, which is your directory name,
# so list them rather than assuming — backing up a name that does not exist
# silently creates an empty volume and an empty archive.
docker volume ls --filter name=pies

mkdir -p backup
docker run --rm \
  -v <project>_pies-mongo-data:/mongo \
  -v <project>_pies-mysql-data:/mysql \
  -v <project>_pies-vault-data:/vault \
  -v "$PWD/backup:/backup" alpine \
  tar czf /backup/pies-data-$(date +%Y%m%d).tar.gz /mongo /mysql /vault

tar tzf backup/pies-data-*.tar.gz | head    # confirm it is not empty

Keep your configuration. .env, your licence file, and the Vault key files (.vault-root-token, .vault-unseal-key) are not in any image. Copy them somewhere safe. Losing the unseal key means losing access to stored credentials.

Read the release notes for anything between your version and the target. Skipping several releases at once is supported, but the notes are where any one-off step would be.

Upgrading from the registry

# 1 · set the target release
#     edit .env:  PIES_VERSION=1.7.0

# 2 · fetch the new images
docker compose pull

# 3 · restart onto them
docker compose up -d

# 4 · unseal Vault
./scripts/init-vault.sh

Step 4 is not optional. Vault seals itself whenever its container restarts, and a sealed Vault takes the AI service and parts of the platform down with it. Re-running init-vault.sh unseals it from the key stored beside your compose file; it is safe to run on an already-initialised Vault and does nothing if Vault is already unsealed. Until an auto-unseal is available, treat this as part of every restart, not just upgrades.

Upgrading from a package

Air-gapped installations get a new .tar.gz instead of pulling.

# extract the new package ALONGSIDE the old one, not over it
tar xzf pies-studio-1.7.0.tar.gz -C /opt/pies-1.7.0
cd /opt/pies-1.7.0

# carry your configuration across
cp /opt/pies-1.6.0/.env .
cp /opt/pies-1.6.0/pies_studio.license .
cp /opt/pies-1.6.0/.vault-root-token /opt/pies-1.6.0/.vault-unseal-key .

# load the images and start
docker load -i images.tar
docker compose up -d
./scripts/init-vault.sh

Extracting alongside rather than over the top is what makes the rollback below possible: the previous release stays on disk, complete.

Check it came up

docker compose ps        # every service running, none restarting
docker compose logs -f pies-core

Then, in a browser: sign in, open an existing application, and build it. Signing in only proves the front end and the login path work. A clean build is what proves the code generator, the database and the AI service all came up on the new release — and it is the thing most worth knowing before your users find out.

If the interface loads but pages return errors, restart the proxy in front of the platform. A recreated container gets a new address, and a proxy that resolved the old one keeps sending traffic there.

Rolling back

Because the volumes were never replaced, going back is the same operation in reverse:

# edit .env back to the previous PIES_VERSION
docker compose pull
docker compose up -d
./scripts/init-vault.sh

From a package, start the previous directory again — it is still there.

Restore the volume backup only if the data itself is wrong. Reverting the images does not require it, and restoring unnecessarily discards everything created since the backup was taken.

Things that catch people out