PIES Studio 1.9 · Documentation

Installing PIES Studio

How to stand up the platform on your own infrastructure. (Building applications with it is the user manual; running the AI privately is the PIES Private AI manual.)

There are two routes to the same result, and the only difference is where the images come from:

Prerequisites

Your licence caps the CPU cores. An enterprise licence can carry a CPU-core allowance. PIES Studio counts the CPUs its pies-core container can run on — every core of the host unless the container is pinned to fewer. If that count is higher than the licence allows, the platform still starts and you can sign in, but Studio's building features are switched off: New Application and Import are disabled, PIES AI building and app export are refused, and Administration → License shows PIES Studio Disabled — CPU Limit Exceeded. The workspace shows:

Check the core count before you install (nproc) and compare it with your licence. If the server has more cores than the licence, either ask PIES for a licence with a larger allowance, or pin pies-core to that many cores with cpuset (for example cpuset: "0-19" under the pies-core service in docker-compose.yml, then docker compose up -d pies-core). A CPU quota (cpus:) does not lower the count — only cpuset does.

Tenancy. An enterprise install is single-tenant: the whole install is one organisation, licensed to you. There is no screen for creating further organisations; separate groups of people are separated with roles, teams and workspaces inside it. If you need fully separate organisations, run separate installs.

Install Docker if it is not already present:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker                    # applies the group without logging out

Check you can reach Docker before going further:

docker ps

If that prints permission denied while trying to connect to the Docker API at unix:///var/run/docker.sock, your user is not yet in the docker group — run the two commands above (or log out and back in), then try again. Every command in this guide assumes docker ps works without sudo.

This is a one-time step per server: the group membership is permanent, so future sessions and reboots need nothing further. Prefer not to grant it? Membership of the docker group is equivalent to root on that host, so you may instead run the installation commands with sudo.

Route A — install from the registry

1. Download the deployment bundle. It is public — no account or token needed. It contains install.sh, docker-compose.yml, configs/, nginx/, scripts/ and docs/; no application images and no source code, since the images are pulled from the registry during installation.

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
echo "d65dc84f83f02ad103ccbe36ae3c7a31cf82485786fdd6a2517aaee9b22267f8  pies-studio-deploy-1.9.0.tar.gz" | sha256sum -c
tar xzf pies-studio-deploy-1.9.0.tar.gz
cd pies-studio-deploy-1.9.0

You need one thing from PIES: your license file (pies_studio.license), issued with your subscription — it goes in at step 2. All six 1.9 images (pies-core, pies-web, pies-ai, loki, deployer, vision) are public on ghcr.io, so no registry account or token is needed. Before it changes anything on the server, the installer checks every image in the kit's images.txt (those six plus the public database and proxy images) against the registry with the credentials it will pull with, and prints one table of image, pull status and, for a refused image, the missing token scope. If any row is NEEDS TOKEN, it stops there — nothing installed, nothing started; tell PIES, and re-run once the image is reachable. ./install.sh --check-images runs only this check.

2. Add your license — copy the pies_studio.license file you were issued into the same directory as install.sh, before you run the installer:

cp /path/to/pies_studio.license .

Keep the filename as it is, and do not open and re-save the file — it is signed. If you have already started the platform without it, see I started before adding the license.

3. Run the installer.

./install.sh

It asks for the hostname or IP your users will reach PIES Studio on, then checks the server, installs Docker if missing, generates passwords into .env, pulls the images (~5 minutes), starts the platform, initialises and unseals Vault, and waits for it to answer. For an unattended install:

./install.sh --hostname studio.yourcompany.com --non-interactive

Useful options (all are also kept in .env for re-runs):

PIES Studio has its own AI engine and needs no external AI key.

4. Check it is running.

docker compose ps

5. Open http://<PIES_HOSTNAME> and follow First run — create your administrator.

Connecting PIES Private AI

PIES Private AI is not part of this installer: it needs a GPU server and installs separately, on its own machine — see the PIES Private AI manual. Everything else — the IDE, the API, previews — runs without it.

If it is already running, you can give the installer its address so the platform knows where to find it:

./install.sh --llm-url http://<gpu-server>:8000

This is optional. The address and the admin key are set (or changed) at any time in Studio under PIES AI → AI Settings → PIES Private AI, with no reinstall; an address saved there takes precedence over --llm-url.

Route B — install from a package

1. Extract. The air-gapped kit is named pies-studio-deploy-<version>-offline.tar.gz and extracts to a folder of the same name:

tar xzf pies-studio-deploy-1.9.0-offline.tar.gz
cd pies-studio-deploy-1.9.0-offline

The package contains install.sh, images/ (pre-built Docker images), configs/, nginx/ and scripts/.

2. Put the license in place — copy pies_studio.license into this directory, or pass its path with --license:

cp /path/to/pies_studio.license .

3. Install, passing the hostname or IP the platform will answer on. --offline loads the images from ./images/ instead of pulling them:

./install.sh --offline --hostname studio.mycompany.com

Options are additive:

./install.sh --offline --hostname studio.mycompany.com \
    --license /path/to/pies_studio.license \
    --smtp-host smtp.example.com --smtp-port 587 \
    --smtp-user notifications@example.com --smtp-pass "app-password" \
    --smtp-from notifications@example.com

Database and Vault secrets are generated on first install and kept in .env; AI provider keys are added in Studio after sign-in. ./install.sh --help lists every option.

The script loads the images, generates configuration for your hostname, starts the infrastructure (MongoDB, MySQL, Redis, Vault), initialises Vault, starts the application services, and verifies each one.

4. Verify — every service should report [OK]:

5. Open http://<hostname> and follow First run — create your administrator.

First run — create your administrator

The first time you open PIES Studio there are no accounts yet, so it asks you to make one. This happens once: after an administrator exists, the same page shows the normal sign-in form.

1. Activate your license. The page opens on Activate License and asks you to upload pies_studio.license — the same file you copied into the install directory. Copying it there is what makes it available to the platform; whether the platform has already read it depends on the deployment, so expect to upload it here and treat it as the step that completes activation.

You can check what the platform has loaded at any time:

curl -s http://<PIES_HOSTNAME>/core/enterprise/status

{ "license_loaded": false, "setup_complete": false }

license_loaded: false is what puts the page on this step.

2. Create the administrator. A new platform has no accounts, so there is nothing to sign in with until you make one. The install kit does not include a script for this step. For an unattended install, call the platform's setup endpoint once the status call above answers:

curl -s -X POST http://<PIES_HOSTNAME>/core/enterprise/setup \
    -H 'Content-Type: application/json' \
    -d '{"name":"Ada Lovelace","email":"ada@example.com","password":"choose-something-strong"}'

{ "message": "Admin account created successfully", "user_id": "..." }

All three fields are required and the password must be at least 8 characters (HTTP 400 otherwise). Re-running it is safe: once an administrator exists the platform answers HTTP 409 with Setup already completed. Please log in. and creates nothing. Afterwards /core/enterprise/status reports "setup_complete": true.

Or do the same in the browser — the page shows Welcome to PiES Studio and Create your admin account to get started., with an ENTERPRISE licence badge, and asks for:

Submitting it creates the first user, with administrator rights, and shows You're All Set — select Go to Login.

If the server has more CPU cores than your licence allows, signing in shows PIES Studio is disabled… and Administration → License reports Studio features as blocked. Nothing is lost: fix the core count or licence as described under Prerequisites. After changing cpuset, restart pies-core; after getting a new licence, upload it in Administration → License.

3. Sign in with the email and password you just chose. From here on, add colleagues from Administration → Users → Add User, which opens Invite User; Send Invite emails them an invite to set their own password — you never need to hand out this first account.

I started before adding the license

This is the common one. Docker creates an empty folder named pies_studio.license when it mounts a file that is not there yet. The platform finds a folder instead of a license, so Studio keeps asking you to activate one even though the file is now sitting in the directory.

docker compose down
rm -rf pies_studio.license             # the empty folder Docker made
cp /path/to/pies_studio.license .      # the real file
docker compose up -d

Then check it was read:

curl -s http://<PIES_HOSTNAME>/core/enterprise/status

"license_loaded": true means you are past it. You can also just upload the same file through Activate License in the browser — that works whatever state the folder is in.

If you see a sign-in form instead

The setup screen only appears while the platform has no users at all. A sign-in form on a supposedly fresh install means the database already contains one — almost always because the deployment was pointed at an existing MongoDB volume rather than an empty one.

You can confirm this directly:

curl -s http://<PIES_HOSTNAME>/core/enterprise/status

{ "license_loaded": true, "setup_complete": true }

setup_complete: true means an account exists. Either sign in with it, or — if nobody has its credentials — start again against an empty database volume, which returns the platform to the setup screen above. Creating a second administrator through the setup screen is deliberately not possible: the endpoint refuses once any user exists.

Locked out of the only administrator account

People who forget their password select Forgot password? on the sign-in page and receive a one-time link (valid for 60 minutes), and an administrator can send the same link from Administration → Users → Send password reset. Both need a working mail server — without one, the administrator's dialog shows the link to hand over instead.

If the person locked out is the only administrator and email does not work, recover the account from the server. The command runs inside the pies-core container, against the platform database, and changes nothing else:

docker compose exec pies-core ./main reset-password --email admin@example.com

It prints a temporary password — sign in with it and change it straight away. To choose the password yourself, or to get a one-time reset link to open in the browser instead:

docker compose exec pies-core ./main reset-password --email admin@example.com --password 'choose-something-strong'
docker compose exec pies-core ./main reset-password --email admin@example.com --link

Setting a password this way also activates the account, so it recovers an administrator who was deactivated or never accepted their invite. Anyone who can run docker compose on the server can do this, which is why access to the server itself should be as tightly held as the administrator account.

What is running

                    ┌──────────────┐
                    │  Nginx Proxy │ :80
                    └──────┬───────┘
           ┌───────────────┼───────────────┐
    ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
    │  pies-web   │ │  pies-core  │ │   pies-ai   │
    │  IDE (UI)   │ │  REST API   │ │  AI engine  │
    └─────────────┘ └──────┬──────┘ └─────────────┘
                   ┌─────────┴──────┐
       ┌───────────┼──────────────┐
    ┌──▼───┐  ┌────▼─────┐  ┌────▼────────┐
    │ loki │  │ deployer │  │   vision    │
    │build │  │  deploy  │  │ preview UI  │
    └───┬──┘  └──────────┘  └─────────────┘
    ┌──────────────┬┴────────────────┐
┌───▼──┐ ┌───▼──┐ ┌───────▼┐ ┌──────▼─┐
│Mongo │ │Redis │ │  MySQL │ │ Vault  │
└──────┘ └──────┘ └────────┘ └────────┘

Only port 80 (and 443 with TLS) needs to be reachable from outside. The rest are internal to the compose network.

Day-to-day operation

docker compose ps                    # status
docker compose logs -f               # all services
docker compose logs -f pies-core     # one service
docker compose stop                  # stop, keep data
docker compose down -v               # stop and DELETE all data
docker compose up -d                 # start again

Vault seals itself every time its container restarts, and a sealed Vault takes the AI service down with it. After any restart of the stack, run ./scripts/init-vault.sh — it unseals from the key stored beside your compose file, and does nothing if Vault is already open.

Updating: see Upgrading PIES Studio.

Changing hostname or settings: edit .env, re-run ./install.sh, then docker compose up -d to restart the affected services.

HTTPS

Terminate TLS in front of the platform — your existing reverse proxy, a cloud load balancer, or Caddy with Let's Encrypt — forwarding to port 80, and set PIES_HOSTNAME to the public name. Certificates are not managed by the platform itself.

Then tell the installer the address users actually open, scheme and port included, so Studio calls its API over https/wss (without it the browser blocks every API call as mixed content). Re-run it from the kit directory; it keeps your settings and secrets:

./install.sh --non-interactive --public-url https://studio.yourcompany.com

Use the port too when the proxy does not listen on 443, for example --public-url https://studio.yourcompany.com:8443. The value is saved as PIES_PUBLIC_URL in .env.

Distributed deployment

Infrastructure (MongoDB, MySQL, Redis, Vault) can run on a separate server from the application services, or be replaced by managed equivalents. Point the application server's .env at the infrastructure host and open the database ports only to that server.

Private AI

The platform can run its AI on your own GPUs instead of a cloud provider — see the PIES Private AI manual. Once installed, connect it under PIES AI → AI Settings → PIES Private AI (Service URL and admin key).

Troubleshooting

• A service shows [!!] or [--] — docker compose logs <service>. The usual causes are a port already in use, or infrastructure not up yet.
• Cannot reach the web UI — check the firewall on port 80 and that PIES_HOSTNAME matches how you are browsing to it.
• License validation fails — confirm pies_studio.license is in the deployment directory and not expired; the license service logs the reason.
• AI features do nothing — no provider key is set, or governance is routing to a private model that is not reachable.
• Deploying an app fails at the deploy WebSocket — the deployer container must be running (it installs with the preview role) and the proxy must forward /deployer/socket to it with the WebSocket upgrade headers. Bundles before 2026-09-18 shipped no deployer: download the current pies-studio-deploy-1.9.0.tar.gz and re-run ./install.sh.
• Preview does not build — loki needs the Docker socket; check it is mounted and that disk space remains.
• Forgot password emails never arrive — the platform has no working mail server. Ask an administrator to use Send password reset (it shows the link when email fails), or see Locked out of the only administrator account.
• Start over — docker compose down -v deletes all data, then deploy again.

Support

support@pies.io — include docker compose ps, the failing service's logs, and your organization name.