PIES Studio 1.7 · 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

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 docker-compose.yml, .env.example, setup.sh and scripts/; no application images and no source code, since the images are pulled from the registry in step 4.

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

The only thing you need from PIES is your license file (pies_studio.license), issued with your subscription — it goes in at step 3.

2. Configure.

cp .env.example .env
nano .env

Three settings are required:

Everything else is optional:

3. Add your license — copy the pies_studio.license file you were issued into the same directory as docker-compose.yml, before you start the platform:

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.

4. Generate configuration and start.

./setup.sh              # writes service configs from .env
docker compose pull     # ~5 minutes
docker compose up -d
./scripts/init-vault.sh # initialises AND unseals Vault

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

Running PIES Private AI on the same server

The AI engine that runs inside your own network is not started by default, because it needs a GPU server (256 GB+ VRAM). On a machine that meets the specification, start it alongside the platform:

docker compose --profile llm up -d

Everything else — the IDE, the API, previews — runs without it. See the PIES Private AI Installation & Operations Manual for the hardware requirements and first-run model download.

Route B — install from a package

1. Extract.

tar xzf pies-studio.tar.gz
cd pies-studio-*

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

2. Check the license is present — the platform will not start without it:

ls -la pies_studio.license

3. Deploy, passing the hostname or IP the platform will answer on:

./deploy.sh studio.mycompany.com

Options are additive:

./deploy.sh studio.mycompany.com \
    --openai-key sk-xxx --claude-key sk-ant-xxx \
    --smtp-host smtp.example.com --smtp-port 587 \
    --smtp-user notifications@example.com --smtp-pass "app-password" \
    --mysql-pass "strong-password" --redis-pass "another-strong-password"

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. Either run the script that ships with the install:

./create-admin.sh

It waits for the platform to answer, then asks for the name, email and password. For an unattended install, pass them instead:

./create-admin.sh --name "Ada Lovelace" \
    --email ada@example.com --password 'choose-something-strong'

Re-running it is safe: once an administrator exists the platform refuses to create a second one this way, and the script says so rather than failing.

Or do the same in the browser — the page shows Welcome to PIES Studio — create your admin account to get started, and asks for:

Submitting it creates the first user, with administrator rights.

3. Sign in with the email and password you just chose. From here on, add colleagues from Administration → Users, which sends 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.

What is running

                    ┌──────────────┐
                    │  Nginx Proxy │ :80
                    └──────┬───────┘
           ┌───────────────┼───────────────┐
    ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
    │  pies-web   │ │  pies-core  │ │   pies-ai   │
    │  IDE (UI)   │ │  REST API   │ │  AI engine  │
    └─────────────┘ └──────┬──────┘ └─────────────┘
                   ┌─────────┴──────┐
                ┌──▼───┐      ┌──────▼──────┐
                │ loki │      │   vision    │
                │build │      │ 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 ./setup.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 — and set PIES_HOSTNAME to the public name. Certificates are not managed by the platform itself.

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 Administration → AI Settings.

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.
• Preview does not build — loki needs the Docker socket; check it is mounted and that disk space remains.
• 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.