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:
docker pull ghcr.io/frontforge-corporation/report-server:0.9.0It 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.
| Path | What |
|---|---|
/app/reportd, /app/renderd | The binaries (/app is on PATH) |
/app/studio, /app/viewer | The designer and viewer apps |
/app/fonts | The bundled fonts |
/data | The volume: the stores, the git repository, auth.json, keys, the audit log, backups |
/config/config.yaml | Optional, mounted |
/run/secrets/ | Where secret:file:NAME references are read |
- The user is uid and gid 65532 (
nonroot)./databelongs 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
HEALTHCHECKisreportd healthcheck, which calls/livezon reportd's own address and exits 0 or 1.reportd healthcheck --readycalls/readyzinstead. renderd alone hasrenderd --healthcheck, which counts a busy renderd (503) as up. - Platforms:
linux/amd64andlinux/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:
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.comIt 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:
--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:
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.comThe 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
# 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-tokenreportd 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:publicURLisREPORTD_PUBLICURL,templateStore.driverisREPORTD_TEMPLATESTORE_DRIVER,auth.sessions.idleTimeoutisREPORTD_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_TOKENandREPORTD_API_KEY(themcpandtestcommands'), and any variable asecret:env:reference names, which is that secret, not a setting: withadmin.password: secret:env:REPORTD_ADMIN_PASSWORDin the file,REPORTD_ADMIN_PASSWORDis 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.yamlor the shared settings that no setting has (a misspeltdata.suppliedDate, say) is ignored, and reportd logsconfig: no such setting; it is ignoredat start for each one, with the key, the file and the line.reportd config checkprints the same aswarning:lines. A map's own keys (connection names, rate classes) and a secret plugin'sconfigaren't checked. - Secrets stay
secret:references:REPORTD_STATE_POSTGRES_URL=secret:file:postgres-urlreads/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_CONFIGorconfig.yamlis skipped when it isn't there; one named by--configmust 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:
$ 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 /:
| Variable | Value |
|---|---|
REPORTD_CONFIG | /config/config.yaml (optional) |
REPORTD_LISTEN | 0.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_DIR | env,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:
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# 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:
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# 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:
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 setupCodeand open http://localhost:43123/setup with the code.
| Files | What runs |
|---|---|
docker-compose.yml | reportd with renderd inside it, a named volume for /data, the health check, restart: unless-stopped |
… -f postgres.yml | Postgres 17, and reportd's users, keys, roles and sessions in it (state.driver: postgres, state.md) |
… -f split.yml | renderd 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
postgresandsplitfiles runreportd compose-secretsonce in a short-lived container, which makespostgres-password,postgres-url,mfa-keyandlink-key(the keys every node must share on Postgres, state.md) andrenderd-tokenin the bundle'ssecrets/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 is0700and each file0600, 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. Usesudoto read them or to add a file there, such aslicence. On Windows and macOS, Docker Desktop only emulates owners and modes on the folders it shares, so the files stay0644in a0755folder 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 atmpfsat/tmp, and at/var/run/postgresqlfor Postgres), every capability dropped (cap_drop: [ALL]) andno-new-privileges. reportd and renderd need no capability. Two services start as root and keep only what that needs: the one-shotsecretscontainerCHOWN,DAC_OVERRIDEandFOWNER, to write the files and give them to 65532; Postgres those andSETUIDandSETGID, 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/dataand/tmp, say) needs a volume ortmpfsthere.deploy/compose/check.shchecks 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
scalebefore 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 insecrets/licenceand addREPORTD_LICENCE: secret:file:licenceto reportd'senvironment. - Scaling renderd. reportd looks the name
renderdup 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/healthanswers. - Other settings go in reportd's
environmentindocker-compose.yml, or in a config file mounted at/config/config.yamlfor 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 withdocker compose cp. - Upgrading: the next release's bundle, with your
.envcopied into it, finds the same volume (upgrading.md).
Spreading renders
reportd spreads renders over several renderd instances itself; nothing runs in front of them.
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.urlis one, as before.renderer.urlslists several.renderer.discover: dnslooksrenderer.discoverName(host:port) up every 5 seconds and uses every address behind it: a Kubernetes headless Service or a compose service name.renderer.commandstarts one renderd inside and can't go withurlsordiscover. - 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
/healthevery 5 seconds until it answers. When every instance is out or busy, the caller gets503 saturatedwithRetry-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(orRENDERD_TOKEN_FILE) refuses every request withoutAuthorization: Bearer <token>with401 unauthorized, except/health; the comparison takes the same time wherever the tokens differ. renderd inside reportd's container listens on loopback and needs none. /readyzis ready while at least one instance answers, and onstate.driver: postgreswhile Postgres answers.
renderd's /health reports its pool, for dashboards and for scaling on the queue:
{"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.