Documentation / Installing the server

Installing the server

This page is a placeholder. A supported, repeatable production install procedure for the Portrait server does not exist yet. The development instance is built and deployed by hand, and that process is not something we would ask anyone else to follow. Writing this properly (a .deb, a systemd target, a first-run flow, and documentation to match) is planned work, not finished work.

What this guide will cover

When it is written, installing the server will mean provisioning one Linux host and:

  • Installing PostgreSQL 16 and Redis, and creating the Portrait database and roles. Migrations never assume superuser, and the database may live on a different host.
  • Deploying the server package under systemd (one target, five services) pointed at your database and Redis by URL.
  • Running migrations (alembic upgrade head).
  • Terminating TLS at a reverse proxy of your choice, or with the shipped config.
  • Bootstrapping the first administrator. A one-time POST /setup route creates a full-privilege owner role and account. It does anything only while the database has zero administrators, and is restricted to the server’s internal network by the shipped config.
  • Configuring backups. See Backup & restore, which is written and live-verified.

Build from source, or install a package

Portrait will ship both ways:

  • Compiled packages for a plain install: a .deb for the server and an .msi for the Windows agent. Coming with the public beta When they exist, they will be linked here and from the releases page.
  • From source if you run a coding agent or otherwise work close to the code. Building from source is the better path there: the agent can read the tree it is deploying, pin to an exact commit, patch locally, and follow the same README sequence a maintainer does. The repository is the source of truth; the packages are a convenience built from it.

In the meantime

The project’s README carries an interim “Getting started” sequence: provision the host, install the dependencies, deploy under systemd, run migrations, hit /setup, then invite other administrators rather than creating accounts directly. It is accurate for a hand-built install and is what the development instance follows. It is not yet a product.

Once the real procedure exists, this page will be replaced with it.

← How Portrait works Enrolling Windows hosts →