Self hosted install
Piprio runs on the customer's own infrastructure as a set of Docker Compose services. A team that wants the platform inside its own network, behind its own firewall, can stand up a working install on a single virtual machine and label the first document the same afternoon. This page covers what that takes, from a blank VM to a logged-in administrator.
Requirements
Piprio installs on a single Linux host. Everything runs as containers managed by Docker Compose, so the operating system underneath only needs Docker and its Compose plugin. Docker Compose is the only supported orchestrator. There is no Kubernetes or Helm packaging, by design, since the platform targets a single-VM footprint.
| Resource | Minimum | Recommended |
|---|---|---|
| Operating system | Ubuntu 22.04+, RHEL 9+, or Debian 12+ | Ubuntu 24.04 LTS |
| Docker | 24.0 or newer, with the Compose plugin | Latest stable |
| Memory | 16 GB | 32 GB |
| CPU | 4 cores | 8 cores |
| Disk | 100 GB SSD | 500 GB SSD |
| Network | Outbound HTTPS, unless running air-gapped | (same) |
An air-gapped install that uses a local model instead of a cloud one needs roughly 8 GB more memory and 20 GB more disk for the model files.
The installer checks the host before it does anything else. It refuses to continue without Docker 24 or newer and the Compose plugin, and it warns (without blocking) when memory or free disk falls short of the recommended figures. A single command starts it:
cd deploy
bash scripts/install.sh
Running the installer
The installer is interactive. It walks an operator through a short series of prompts, then provisions every service Piprio needs: the database, object storage, the cache, background workers, the web application, and a reverse proxy in front of all of it. There is no unattended or scripted mode. An operator runs it once, in a terminal, and answers the prompts.
After the requirement checks pass, the installer asks for four things:
- The public domain name the platform will be reached at.
- A contact email noted for the eventual production certificate. The installer records it but does not request a certificate on the operator's behalf. It always issues a self-signed one and leaves the trusted certificate as a later manual swap.
- The choice of AI model provider, either a hosted cloud model or a local model that runs on the same host for air-gapped sites.
- The email address for the first administrator account.
From those answers it does the rest on its own. It generates the secrets the platform needs, writes the configuration file, creates a TLS certificate, pulls the container images, brings up the database and cache first, waits for them to report healthy, then starts the application and waits for it to answer its own health check. The whole run is non-destructive on a clean host and prints a clear pass or fail at each stage.
Two compose definitions ship with the platform. One bundles object storage into the deployment for sites that want everything self-contained on the VM. The other expects an external object store, which suits a cloud-hosted install backed by a managed bucket. The installer uses the self-contained on-premise definition.
# Self-contained on-premise deployment (bundled object storage)
docker compose -f docker-compose.onprem.yml up -d
# Cloud-hosted deployment (external object storage)
docker compose -f docker-compose.prod.yml up -d
An optional air-gapped profile adds a local model container, so a site with no outbound internet can still run AI extraction. A second optional profile turns on automatic image updates. Both are opt-in.
# Air-gapped: bundle a local model, no internet required
docker compose -f docker-compose.onprem.yml --profile airgapped up -d
Database schema setup is not a step the operator runs. The backend container applies any pending migrations automatically when it starts, and tracks what has already run so a restart never re-applies the same change. An operator who upgrades to a newer version gets the new schema applied the next time the backend comes up, with no manual command.
Configuration
The installer draws a clean line between what an operator supplies and what the platform generates for itself.
The operator supplies four pieces of information: the domain, the certificate email, the AI provider choice, and the first administrator's email. The cloud-model path also asks for the provider's API key. The local-model path asks which model to download instead, and pulls it during install.
Everything sensitive is generated, not typed. The installer creates the database password, the credential-encryption key, the token-signing key, and the object-storage credentials, all as long random values. The encryption and signing keys are written as Docker secrets with locked-down permissions, kept out of the main configuration file, and never printed to the screen. Connector credentials that operators add later are encrypted with that generated key before they touch disk, so a database dump never carries readable passwords.
The interactive path covers the two common cases: a hosted cloud model, or a local model on the same host for air-gapped sites. Connecting Piprio to a third type of provider, an external endpoint that speaks the common chat-completions interface, is supported but is set after install by editing the configuration file directly rather than through a prompt.
This page stops at the level a buyer needs to judge the install. The full set of tunable values, connection pool sizing, log levels, file-size ceilings, retention windows, optional email and metrics integrations, lives in the operator runbook that ships in the deployment package, alongside the annotated configuration template.
First admin user
Piprio has no public sign-up. The first account is created during install, and that first user is an administrator who can then invite everyone else.
As its last step the installer creates the administrator from the email collected earlier, generates a strong one-time password for it, and prints both the login URL and the credentials to the terminal. The password is shown once and never again, so it has to be saved at that moment. After the first sign-in the administrator changes the password and invites the rest of the organization.
When the install finishes, the screen shows the platform URL, the administrator email, and the generated password, along with a reminder to save the password and to replace the placeholder certificate before going live.
Verifying the install
A health-check script ships alongside the installer. It confirms that every container is running, that the database and cache answer, and that the application responds on both its liveness and readiness checks. It also reports the current database size and free disk on the host.
bash scripts/health-check.sh
The script prints a pass, fail, or warning line per check and a final tally. A non-zero exit means at least one check failed, and it points at the command to read that service's logs. The same single compose command streams logs from any service for a closer look.
docker compose -f docker-compose.onprem.yml logs -f
A successful run leaves a fully working platform: the administrator can sign in over HTTPS, create a labeling spec, upload a document, and have a reviewer label it.
Security and the default certificate
The reverse proxy terminates TLS and redirects all plain-HTTP traffic to HTTPS. Out of the box the certificate is self-signed, generated during install for the chosen domain. That is enough to get the platform up and reachable over an encrypted connection, but browsers will warn on it, so it is meant to be replaced before the platform goes into real use.
Swapping in a trusted certificate is a manual step: drop the real certificate and key into the certificate directory, restart the proxy, then turn on strict transport security. That last switch is one-way in practice, since browsers cache the strict-transport policy for a year, so it should only be flipped once a trusted certificate is in place. The deployment notes spell out the exact sequence and the reason for the order.
Tenant data sits in isolated Postgres schemas, one per organization, which keeps each customer's labeled documents and audit history walled off from every other tenant inside the shared database. That isolation model, and the encryption-at-rest of stored connector credentials, are the parts of the install most relevant to a security review.
Next steps
A fresh install is the starting point, not the finish line. The deployment package includes an operator runbook that covers day-two operations the buyer's team will want before going to production:
- Backing up and restoring the platform, including the database, stored documents, and the keys needed to read encrypted credentials. See
docs/operations/backup-restore.md. - Upgrading to a new version, with a pre-flight check, an automatic backup, and a staged restart that keeps the platform reachable. See
docs/operations/upgrades.md. - The full configuration reference, in the annotated template and on-premise notes that ship in the deployment package.
For a buyer weighing self-hosting against a managed option, the short version is this: a single guided installer takes a clean VM to a running, HTTPS-reachable platform with a working administrator account, and the same package carries the backup, restore, and upgrade tooling needed to run it past day one.