1 Architecture and Requirements

TraxrGRC is a self-hosted web application that runs as a small set of Docker containers on one server. Each organization gets its own instance: its own application, background worker, database and file store. Nothing is shared between instances, and there is no central service that an instance calls home to.

This chapter describes the parts of an instance, how they connect, and what the server and the network must provide. Read it before you install, and keep it at hand when you plan firewall rules, monitoring and backups.

1.1 Components

An instance is defined by docker-compose.yml in the release directory. One application image, built from the release's Dockerfile, runs in three roles (migrate, web and worker); the other services use public images.

The instance keeps its state in four named Docker volumes. Compose prefixes each with the project name (grc unless you set COMPOSE_PROJECT_NAME), so the uploads volume of the default project is grc_uploads.

The database and the uploads volume are everything you must back up. The two Caddy volumes can be recreated: Caddy requests new certificates if they are lost.

1.2 How the components connect

The containers share a private Docker network. Only two things listen on the host: the web port (on 127.0.0.1:3000 by default) and, with the tls profile, Caddy on ports 80 and 443.

1. A browser or API client connects to Caddy (or your own reverse proxy) over HTTPS. The proxy forwards the request to web:3000.
2. web reads and writes the database as the application role. It never writes files anywhere except the uploads volume and two in-memory directories (/tmp and its Next.js cache).
3. When something has to happen later or outside the request (an email, a notification rule), web puts a job on the queue. The queue is pg-boss, stored in the database's own pgboss schema, so there is no separate message broker.
4. worker takes jobs from the queue, runs the scheduled tasks, and sends email through the SMTP server configured under Settings → Integrations.

Start-up order is enforced by Compose: migrate waits for db to report healthy, and web and worker start only after migrate has finished successfully. If migrate fails, web and worker do not start, so the application never runs against a database it has not prepared.

1.2.1 Database roles

The database has two login roles, and the split is part of how the audit log is protected.

The application role can read and write the application's tables, but on the audit log it can only read and add entries; it owns nothing in the application's schema and so cannot alter, disable or drop the audit log's triggers. It owns the pgboss schema, which the queue needs. Neither web nor worker is given the owner's password.

migrate creates the application role on the first start and, on every start, sets its password from APP_DB_PASSWORD and reapplies its grants. A changed password or a new table needs nothing more than docker compose up -d.

1.2.2 Background jobs

The worker registers these queues and schedules. All schedules are in UTC.

Saving the digest schedule under Settings → Notifications applies it at once; no restart is needed. If the save cannot reach the job queue (for example because the worker has never run), the page says so and the worker picks up the saved schedule when it next starts.

Jobs wait in the database while the worker is stopped and run when it comes back, so stopping the worker delays email; it does not lose it.

1.2.3 Container hardening

web, worker and migrate run as an unprivileged user (uid 100, gid 101) with a read-only root filesystem, no Linux capabilities and no-new-privileges. The application code in the image is owned by root, so even the application cannot change it. The only writable places are the uploads volume, /tmp and, for web, /app/.next/cache (both in memory and emptied on restart). The bundled Caddy runs with the same settings, keeping only the capability to listen on ports below 1024. The image contains production dependencies only.

1.3 Host requirements

1.4 Supported browsers

TraxrGRC is a Next.js 16 application and supports the browsers Next.js supports: current versions of Chrome, Edge and Firefox (version 111 or later) and Safari 16.4 or later, on desktop. The product's automated end-to-end tests run in Chromium and Firefox. JavaScript and cookies must be enabled.

1.5 Network ports

SAML single sign-on needs no outbound connection from the server: the identity provider's response travels through the user's browser.