PIES Studio 1.9 · 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.

Check your licence was issued for 1.9. From 1.9 a licence must be signed by a PIES signing key. A licence issued before 1.9 is rejected after the upgrade with license signature verification failed … was issued before PIES 1.9. Ask PIES support for a reissued licence before you upgrade, and put it in place of pies_studio.license.

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

docker compose stop

# The 1.9 bundle names the Compose project "pies-studio", so volumes are
# pies-studio_<name>. List them first — backing up a name that does not exist
# silently creates an empty volume and an empty archive. You should see all
# three: pies-studio_mongo-data, pies-studio_mysql-data, pies-studio_vault-data.
docker volume ls --filter name=pies-studio

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

# Confirm every volume made it into the archive. Any "EMPTY:" line means that
# volume was not backed up: stop and fix the volume name before upgrading.
for d in mongo mysql vault; do
  n=$(tar tzf backup/pies-data-*.tar.gz | grep -c "^$d/.\+[^/]$" || true)
  echo "$d: $n files"
  [ "$n" -gt 0 ] || echo "EMPTY: $d was not backed up"
done

Keep your configuration. .env (it holds every generated password, the Vault token and PIES_SERVICE_SECRET) and your licence file are not in any image. Copy them somewhere safe. Losing .env means losing access to your databases and stored credentials.

Which installs this covers. These steps are for installations made with the 1.9 deployment bundle (install.sh). The 1.7 bundle (setup.sh) used a different layout; to move a 1.7 installation to 1.9, contact PIES support.

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

Download the new bundle, extract it alongside the current one, carry your configuration across, and re-run the installer. The installer reuses every secret already in .env and writes the new image tag.

curl -fsSL -o pies-studio-deploy-1.9.0.tar.gz \
  https://github.com/pies-io/pies-studio-releases/releases/download/deploy-1.9.0/pies-studio-deploy-1.9.0.tar.gz
tar xzf pies-studio-deploy-1.9.0.tar.gz
cd pies-studio-deploy-1.9.0

# carry your configuration across from the previous directory
cp ../<previous-bundle>/.env .
cp ../<previous-bundle>/pies_studio.license .

# stop the old release, then install the new one over the same volumes
( cd ../<previous-bundle> && docker compose stop )
./install.sh --version release-1.9

--version matters on a re-run: without it (or PIES_VERSION), the installer keeps the version already recorded in .env. The installer also regenerates the service configs, starts the platform and prepares Vault, so there is no separate docker compose pull or init-vault.sh step.

1.9.0 bundles before 2026-09-18 shipped no deploy engine. If you installed from an earlier copy of pies-studio-deploy-1.9.0.tar.gz, deploying an app fails at the deploy WebSocket: the bundle carried no deployer container and its nginx config had no /deployer/ routes. Re-running your existing install.sh cannot fix that — the missing pieces are in the bundle, not in the images. Download the current bundle (SHA-256 d65dc84f83f02ad103ccbe36ae3c7a31cf82485786fdd6a2517aaee9b22267f8), extract it, copy your .env and licence across as above, and run ./install.sh --version release-1.9. It adds the deployer container, renders its config, reloads the proxy with the new routes and leaves your volumes untouched.

PIES_SERVICE_SECRET. From 1.9, pies-core and pies-ai must share the same PIES_SERVICE_SECRET, or pies-core refuses the AI service's calls and AI features fail. The installer creates it on the first 1.9 run, keeps the value already in .env on every later run, and writes it to both services. If you edit .env by hand, leave it in place and re-run ./install.sh rather than changing it for one service only.

Upgrading from a package

Air-gapped installations get a new offline .tar.gz with the images in images/. The steps are the same as above; the installer loads the images from ./images/ instead of pulling:

tar xzf pies-studio-deploy-1.9.0-offline.tar.gz
cd pies-studio-deploy-1.9.0-offline
cp ../<previous-bundle>/.env ../<previous-bundle>/pies_studio.license .
( cd ../<previous-bundle> && docker compose stop )
./install.sh --version release-1.9 --offline

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:

docker compose stop                       # in the new directory
cd ../<previous-bundle>
./install.sh --version <previous-version> # re-uses that directory's .env

The previous directory is still on disk, complete, with its own .env.

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