trellum
Docs / Install / Choose how to run Trellum

Choose how to run Trellum

Applies to: latest

Choose the shape that matches the job you need to do. A deployment is the whole installation; a host is one machine in it.

Choose a path

You want to Start at
Try it locally Try Trellum locally — framework examples and an optional disposable portal demo
Run the portal on one server Deploy on one server — web, worker, database, and persistent files
Build more reports at once on one server Scale builds on one server — more runners on the same host
Run builds across multiple servers Run across multiple servers — runner hosts with shared PostgreSQL and files

You can also build in CI and serve portable reports from a static host without the portal. A managed PostgreSQL database and optional object storage are choices inside these deployment shapes, not separate install methods.

The framework needs no installation of the portal — you can build reports on your laptop first and stand up the portal later, against the same repository. The framework overview explains the boundary between the two; framework capabilities is the index to the standalone API guide.

What the terms mean

  • web — the portal service
  • combined worker — scheduling and report builds in one process
  • coordinator — scheduling and maintenance; keep one active coordinator
  • runner — claims queued work and builds reports
  • sandbox — a temporary isolated container for one build

Additional coordinators stand by until they can acquire the coordinator lock.

What a deployment contains

  • web — the portal itself, behind your reverse proxy
  • worker, coordinator, runner — the default worker combines scheduling and report builds. A split deployment uses one coordinator for scheduling, cleanup, and scheduled delivery, plus one or more runners for builds.
  • db — Postgres 16, which also holds the build queue, so there is no separate queue or cache service to run and monitor
  • persistent data storage — studio checkouts and project files, uploaded data-source files, live run logs, audit archives, and local report output; the web, coordinator, and every runner need access to the same data directory

Requirements

  • Docker Engine 26+ for the default named-volume storage, or Docker Engine 25+ with host-folder storage. Use a current patched engine and the Compose plugin (v2.24+).
  • 2+ CPUs and 4+ GB RAM to start; report builds are the hungry part, so size to your reports rather than your viewer count
  • A DNS name and a reverse proxy (Caddy, Traefik, nginx) terminating TLS, configured to accept large request bodies if you'll let people upload data files through the portal — see Sizing

Note

Build workload usually drives CPU and RAM. Serving pre-built reports also needs capacity, and reports with opt-in live queries use web and data-source capacity too.

Next

Continue to Deploy on one server for the complete installation, or choose Storage before planning a multi-host layout.