Skip to content

Docker and compose ​

Frontforge Report Server ships as one container image with two modes: reportd with renderd inside it (the default), or renderd alone. The compose setup in the public releases repository runs it on one machine (Compose); helm.md runs it on Kubernetes. The first start is the setup wizard (setup.md), which asks for your licence: every install needs one, and the Community licence is free (licence.md).

The image ​

The image is ghcr.io/frontforge-corporation/report-server, tagged with each version, its x.y, and latest:

bash
docker pull ghcr.io/frontforge-corporation/report-server:0.9.0

It is built on gcr.io/distroless/cc-debian13:nonroot (Debian 13, from 0.10.0; earlier releases are on Debian 12): no shell, no package manager, glibc for renderd.

PathWhat
/app/reportd, /app/renderdThe binaries (/app is on PATH)
/app/studio, /app/viewerThe designer and viewer apps
/app/fontsThe bundled fonts
/dataThe volume: the stores, the git repository, auth.json, keys, the audit log, backups
/config/config.yamlOptional, mounted
/run/secrets/Where secret:file:NAME references are read
  • The user is uid and gid 65532 (nonroot). /data belongs to it in the image, so a new named volume does too; a bind mount must be writable by 65532.
  • Ports: 43123 for reportd, the only port the image exposes. renderd alone listens on 43124, and only with --token-file: without a token it refuses any address but loopback (security.md).
  • Health: the image's HEALTHCHECK is reportd healthcheck, which calls /livez on reportd's own address and exits 0 or 1. reportd healthcheck --ready calls /readyz instead. renderd alone has renderd --healthcheck, which counts a busy renderd (503) as up.
  • Platforms: linux/amd64 and linux/arm64.
  • Labels: the OCI labels for the version, commit, source, vendor and licence.
  • Not in it: veraPDF.

Checking the image ​

From 0.10.0, each release's image is signed with cosign, keyless: the signature's certificate names the workflow that made it, release.yml in frontforge-corporation/report-server, at the release's tag, and Sigstore's public transparency log records it. To check an image before you run it:

bash
cosign verify ghcr.io/frontforge-corporation/report-server:0.10.0 \
  --certificate-identity https://github.com/frontforge-corporation/report-server/.github/workflows/release.yml@refs/tags/v0.10.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

It prints what it checked and exits 0, or fails if the image wasn't signed by that workflow at that tag. To accept any release's image, name the identity by a pattern instead of --certificate-identity:

bash
  --certificate-identity-regexp '^https://github\.com/frontforge-corporation/report-server/\.github/workflows/release\.yml@refs/tags/v'

The image's SBOM (CycloneDX) is attached to it as a signed attestation. verify-attestation checks it the same way, and prints it:

bash
cosign verify-attestation --type cyclonedx ghcr.io/frontforge-corporation/report-server:0.10.0 \
  --certificate-identity https://github.com/frontforge-corporation/report-server/.github/workflows/release.yml@refs/tags/v0.10.0 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The same SBOM is among each release's downloads, report-server-<version>.sbom.cdx.json. A policy that checks images as they are deployed, such as Kyverno's or Sigstore's policy-controller, takes the same identity and issuer. The signature is on the image's digest, which covers both platforms, so cosign verify takes ghcr.io/frontforge-corporation/report-server@sha256:…, with the digest from the release notes, as well as a tag.

Releases before 0.10.0 aren't signed.

Its modes ​

bash
# reportd, with renderd inside it on loopback
docker run -d -p 43123:43123 -v reports:/data ghcr.io/frontforge-corporation/report-server:0.9.0

# renderd alone, for reportd elsewhere to spread renders over
docker run -d -p 43124:43124 -v ./renderd-token:/run/secrets/renderd-token:ro \
  ghcr.io/frontforge-corporation/report-server:0.9.0 renderd --listen 0.0.0.0:43124 --token-file /run/secrets/renderd-token

reportd uses renderd elsewhere when REPORTD_RENDERER_COMMAND is set to nothing and REPORTD_RENDERER_URL, REPORTD_RENDERER_URLS or REPORTD_RENDERER_DISCOVER says where (Spreading renders).

Settings from the environment ​

Every setting can come from a REPORTD_ variable, so a container needs no config file. The configuration reference lists each setting with its variable.

  • Names. REPORTD_ and the setting's YAML path in capitals, each level joined by _, ignoring the camel case inside a level: publicURL is REPORTD_PUBLICURL, templateStore.driver is REPORTD_TEMPLATESTORE_DRIVER, auth.sessions.idleTimeout is REPORTD_AUTH_SESSIONS_IDLETIMEOUT.
  • Values are parsed as the setting's type: true/false, whole numbers, durations (2h, 30m, 90s), and comma-separated lists (REPORTD_SOURCECONTROL_ENVIRONMENTS=dev,test,prod). A variable set to nothing sets the setting to nothing: REPORTD_RENDERER_COMMAND= turns off the renderd inside.
  • Lists of objects and maps stay in the file: auth.oidc.providers, auth.saml.providers, connections, jobs.webhooks.endpoints, limits.rate, extensions, assets.remote. A variable naming one, or anything inside one, is refused at start.
  • Unknown variables are refused at start, so a typo fails loudly. Allowed besides the settings: REPORTD_CONFIG, REPORTD_TOKEN and REPORTD_API_KEY (the mcp and test commands'), and any variable a secret:env: reference names, which is that secret, not a setting: with admin.password: secret:env:REPORTD_ADMIN_PASSWORD in the file, REPORTD_ADMIN_PASSWORD is the password.
  • Unknown keys in the files are a warning, not an error, so a config written for another version still starts: a key in the config file, settings.yaml or the shared settings that no setting has (a misspelt data.suppliedDate, say) is ignored, and reportd logs config: no such setting; it is ignored at start for each one, with the key, the file and the line. reportd config check prints the same as warning: lines. A map's own keys (connection names, rate classes) and a secret plugin's config aren't checked.
  • Secrets stay secret: references: REPORTD_STATE_POSTGRES_URL=secret:file:postgres-url reads /run/secrets/postgres-url.
  • Order: the defaults, then the config file, then dataDir/settings.yaml (what setup wrote), then the environment. The config file is optional: $REPORTD_CONFIG or config.yaml is skipped when it isn't there; one named by --config must be.

reportd config check makes the checks reportd makes at start, its secret plugins started, and says what is wrong. reportd config show prints the settings reportd runs on, as YAML, with secrets masked (a literal where a secret goes, and a password in a URL); a secret: reference shows as it is. --origin marks each value with where it came from:

text
$ docker exec rf reportd config show --origin
# config file: none
# settings: /data/settings.yaml
listen: 0.0.0.0:43123 # env REPORTD_LISTEN
publicURL: https://reports.example.com # settings
dataDir: /data # env REPORTD_DATADIR
...

The image sets these, over reportd's workstation defaults. The store paths keep their defaults (data/templates, data/reports, data/repo), which land in /data since the image's working folder is /:

VariableValue
REPORTD_CONFIG/config/config.yaml (optional)
REPORTD_LISTEN0.0.0.0:43123
REPORTD_DATADIR/data
REPORTD_RENDERER_COMMAND/app/renderd
REPORTD_STUDIO_DIR, REPORTD_VIEWER_DIR/app/studio, /app/viewer
REPORTD_SECRETS_PROVIDERS, REPORTD_SECRETS_DIRenv,file, /run/secrets
REPORTD_SECRETS_PLUGINDIRS/app/plugins

The environment wins over the file, so a setting the image sets can be changed only by a variable.

Secret plugins ​

The image carries our store plugin, reportd-secret-store, in /app/plugins: part of the image, owned by root, read-only, and built from the same release as reportd. Nothing runs until config.yaml names it under secrets.plugins (data connections). Its master key is a file in /run/secrets, as a compose secret:

yaml
services:
  reportd:
    secrets: [store-key]
    volumes:
      - ./config.yaml:/config/config.yaml:ro
secrets:
  store-key:
    file: ./store-key        # openssl rand -base64 32 > store-key; keep a copy apart from the backups
yaml
# config.yaml
secrets:
  plugins:
    - name: store
      program: reportd-secret-store
      config: { key: secret:file:store-key }

It also carries our HashiCorp Vault plugin, reportd-secret-vault, likewise off until config.yaml names it, which needs a licence with secret-vaults (data connections). Its sign-in credential is a file in /run/secrets too, such as an AppRole secret id:

yaml
services:
  reportd:
    secrets: [vault-secret-id, vault-ca.pem]
secrets:
  vault-secret-id:
    file: ./vault-secret-id
  vault-ca.pem:
    file: ./vault-ca.pem     # only when a private authority signs Vault's certificate
yaml
# config.yaml
secrets:
  plugins:
    - name: vault
      program: reportd-secret-vault
      config:
        address: https://vault.corp.example:8200
        caFile: /run/secrets/vault-ca.pem
        auth: { method: approle, roleId: 7c1e…, secretId: secret:file:vault-secret-id }

The Azure Key Vault plugin, reportd-secret-azure, is in /app/plugins too, off in the same way, and needs a licence with secret-vaults. On an Azure VM it signs in with the machine's managed identity and needs no secret; elsewhere, its client secret is a compose secret like the key above (data connections).

The image also carries the AWS Secrets Manager plugin, reportd-secret-aws, off in the same way, which needs a licence with secret-vaults (data connections). On ECS, EKS or EC2 it reads as the task's, pod's or instance's role; list the variables that role's credentials come by in its env, such as env: [AWS_CONTAINER_CREDENTIALS_RELATIVE_URI] for an ECS task role.

A plugin of your own, or a third party's, goes in a folder you mount, read-only, and add to the plugin folders. The image sets them by a variable, which wins over the file, so add it there: REPORTD_SECRETS_PLUGINDIRS=/app/plugins,/plugins (writing a secret plugin).

The image ships no example reports. The studio lists the example gallery from Frontforge's public releases repository on GitHub, and copies in the one someone picks (starting from a template). On a machine without internet access, set REPORTD_EXAMPLES_GALLERY to the gallery/ or examples/ folder of a clone of that repository, or to off.

reportd checks once a day for a newer release, and tells administrators in the studio (updates.md). Without internet access the check fails quietly; REPORTD_UPDATES_CHECK=false turns it off.

Compose ​

The compose setup runs Frontforge Report Server on one machine. It is the compose/ folder of the public report-server-releases repository: its main branch is the newest release, release/<x.y> the newest of a line, and v<version> one release, and in each, docker-compose.yml names the image of that version. Clone it, copy .env.example to .env and edit it: the port, and REPORTD_PUBLICURL if you know it. Then:

bash
git clone https://github.com/frontforge-corporation/report-server-releases.git
cd report-server-releases/compose
cp .env.example .env
docker compose up -d
docker compose logs reportd | grep setupCode

and open http://localhost:43123/setup with the code.

FilesWhat runs
docker-compose.ymlreportd with renderd inside it, a named volume for /data, the health check, restart: unless-stopped
… -f postgres.ymlPostgres 17, and reportd's users, keys, roles and sessions in it (state.driver: postgres, state.md)
… -f split.ymlrenderd as its own service, which reportd spreads renders over: docker compose -f docker-compose.yml -f split.yml up -d --scale renderd=3

The two extra files are add-ons: they change and add to what docker-compose.yml defines, so list them after it. They can go together.

  • Secrets. The postgres and split files run reportd compose-secrets once in a short-lived container, which makes postgres-password, postgres-url, mfa-key and link-key (the keys every node must share on Postgres, state.md) and renderd-token in the bundle's secrets/ folder and keeps any that are there. Keep that folder: git ignores what's in it, as it does .env. reportd, Postgres and renderd read them from /run/secrets/. On a Linux host, each run also locks them: the folder is 0700 and each file 0600, owned by 65532, the image's user (Postgres reads its password as root, before it drops to its own user), so the host's other users can't read them. Use sudo to read them or to add a file there, such as licence. On Windows and macOS, Docker Desktop only emulates owners and modes on the folders it shares, so the files stay 0644 in a 0755 folder and your account's permissions on the folder are what keep them.
  • Hardening. Every service runs with a read-only root file system (read_only, with a tmpfs at /tmp, and at /var/run/postgresql for Postgres), every capability dropped (cap_drop: [ALL]) and no-new-privileges. reportd and renderd need no capability. Two services start as root and keep only what that needs: the one-shot secrets container CHOWN, DAC_OVERRIDE and FOWNER, to write the files and give them to 65532; Postgres those and SETUID and SETGID, for its entrypoint to read its password and drop to its own user. A setting of yours that writes somewhere else in a container (a config file pointing a path outside /data and /tmp, say) needs a volume or tmpfs there. deploy/compose/check.sh checks every profile for this.
  • A licence. Postgres state and renderd as its own service are "scale" features (licence.md). A new install with either still starts, and the setup wizard asks for a licence with scale before it will finish. An install that already has users opens only the Licence dialog until one is installed. An install from before licences has 60 days first. To give the licence before the first start instead, put it in secrets/licence and add REPORTD_LICENCE: secret:file:licence to reportd's environment.
  • Scaling renderd. reportd looks the name renderd up every 5 seconds and uses every container behind it, so scaling up or down takes effect within seconds. A stopped instance is left out after two failures and taken back when its /health answers.
  • Other settings go in reportd's environment in docker-compose.yml, or in a config file mounted at /config/config.yaml for lists of objects such as sign-in providers.
  • Backups: docker compose exec reportd reportd backup --out /data/backups/manual.tar.gz (backup.md), then copy it off the volume with docker compose cp.
  • Upgrading: the next release's bundle, with your .env copied into it, finds the same volume (upgrading.md).

Spreading renders ​

reportd spreads renders over several renderd instances itself; nothing runs in front of them.

yaml
renderer:
  command: ""                                    # no renderd inside
  urls: [http://render-1:43124, http://render-2:43124]
  # or: discover: dns, discoverName: renderd-headless.reports.svc:43124
  token: secret:file:renderd-token               # what renderd --token-file requires
  • Where the instances are: renderer.url is one, as before. renderer.urls lists several. renderer.discover: dns looks renderer.discoverName (host:port) up every 5 seconds and uses every address behind it: a Kubernetes headless Service or a compose service name. renderer.command starts one renderd inside and can't go with urls or discover.
  • Which one a call goes to: the instance with the fewest calls in flight from this reportd; ties go in turn. The asset uploads that follow a 409 missing-assets, and the call again, stay on the instance that asked, since each renderd has its own asset cache. A font is asked of each instance until one has it.
  • Retrying: a 503 saturated, a refused connection or one closed before any answer goes once more to another instance. Nothing else is tried again, nor a call that timed out, since it may still be running.
  • Instances left out: one that fails twice in a row is left out and asked for /health every 5 seconds until it answers. When every instance is out or busy, the caller gets 503 saturated with Retry-After, and reportd logs a warning at most once a minute: the sign that more instances are needed.
  • The token is the same for every instance. renderd started with --token-file (or RENDERD_TOKEN_FILE) refuses every request without Authorization: Bearer <token> with 401 unauthorized, except /health; the comparison takes the same time wherever the tokens differ. renderd inside reportd's container listens on loopback and needs none.
  • /readyz is ready while at least one instance answers, and on state.driver: postgres while Postgres answers.

renderd's /health reports its pool, for dashboards and for scaling on the queue:

json
{"status": "ok", "version": "0.9.0", "workers": 4, "running": 1, "queued": 0, "queueLimit": 16}

workers follows the CPUs renderd may use (a container's CPU limit), and queueLimit is four times that; past it renderd answers 503 saturated.