Reportforge

Appearance

First-run setup ​

A new reportd has no users. Instead of a default password, it starts in setup mode, and the setup wizard (in the studio at /setup, or reportd setup in a terminal) creates the administrator and the first settings.

Setup mode ​

reportd is in setup mode while no user exists and admin.password is unset. An install that sets admin.password (every config reportd init-config writes, Helm's admin.existingSecret) never is: it creates its administrator as before.

  • The code. reportd makes a one-time setup code (16 characters in groups of four) and keeps it in dataDir/setup-code (mode 0600). It writes it to its log at every start while in setup mode, as setupCode=…: docker compose logs reportd | grep setupCode, or kubectl logs …. With text logs (the default), a frame below that line shows it at a glance:

    text
    # ******SETUP CODE*******
# * ABCD-EFGH-JKMN-PQRS *
# ***********************

    JSON logs (logging.format: json) have the line only, to keep one object a line.

  • What answers: the health probes, the studio's and viewer's files, and /v1/setup. Every other /v1 request, the MCP endpoint and report links answer 503 setup-required; the studio goes to /setup.

  • Wrong codes count in the signin rate-limit class and in the sign-in throttle, by address: twenty wrong codes from an address in 15 minutes stop it for a while, and nobody else.

  • Setup mode ends once the administrator exists: the code file is deleted, and /v1/setup answers 404 from then on.

The steps ​

The wizard and reportd setup ask the same steps and run the same checks (internal/setup).

  1. Administrator: a username, and a password of at least 10 characters that isn't the username. Optionally, administrators must have a second factor (auth.mfa: admins): they set one up at their first sign-in.
  2. Licence: paste a licence or choose its file, or Continue with Community, which the step describes (licence.md). A licence that doesn't verify, hasn't started or has lapsed is an error. When the licence setting fixes one, the step only shows it. When the configuration turns on what needs a licence (SSO providers, Postgres state or separate renderd instances), the step lists those settings, doesn't offer Community, and is an error until the licence grants them (licence.md).
  3. Address: the public URL. The wizard starts from the browser's address. A host that is an IP address gets a warning (passkeys need a domain name), and so does plain http on a host other than localhost. The step also offers the version check (updates.check, on), and says what it sends: once a day reportd asks GitHub for the latest release, with no version, install ID or usage in the request (updates.md). Turned off, setup writes updates.check: false.
  4. Environments: their names and promotion order, by default dev, test, uat, prod. They are hard to change once templates exist. Without a licence with environments, more than one is a warning: only the first is usable for publishing, so Community wants one.
  5. Storage: checked, not chosen, since it decides where setup's own results go: the data folder is writable and has room (a warning under 1 GB, an error under 100 MB), the template and report stores open, git works and its remote answers, and Postgres answers on state.driver: postgres.
  6. Engine: renderd answers, its fonts load, and a test render of a small built-in page shows the result.
  7. Summary: what will be written and where, the settings that are fixed and where each comes from, and links to sso.md, backup.md and rate-limits.md.

An error stops a step; a warning is shown once, then Next goes on. Email (SMTP) gets a step when that item exists.

Setup adds no reports. The catalog starts empty, and offers the example gallery: picking an example copies it in (starting from a template).

What setup writes ​

  • The administrator goes into the auth store (auth.json on state.driver: file, Postgres on postgres), as a hash. The password is never written to a file, and doesn't have to be changed at the first sign-in.
  • The other settings go into dataDir/settings.yaml (mode 0600): publicURL, sourceControl.environments and auth.mfa. reportd reads it over the config file and under the environment (docker.md). A setting the config file or a REPORTD_ variable sets is fixed: the wizard shows it read-only, with where it comes from, and setup leaves it.
  • The licence, when the licence step has one, is installed as reportd licence install would: into dataDir/licence, or Postgres on postgres.
  • The audit log gets setup.complete, with the administrator's name and the settings written, and licence.install <id> for a licence.

Then reportd starts again in the same process on its new settings (environments, passkeys and sign-in providers read them at start). It keeps its listener open meanwhile, so requests wait rather than fail. The wizard signs the new administrator in and opens the catalog.

reportd setup ​

bash
reportd setup                                  # a stopped reportd's data, with its config
reportd setup --url http://reports:43123 --code ABCD-EFGH-JKMN-PQRS    # a running one
reportd setup --yes --admin-user ada --admin-password-file ./pw --licence-file ./larkmere.licence \
  --public-url https://reports.example.com --environments dev,prod
  • Interactive, it asks each step in turn, the password without echo, until the step's checks pass, then shows the summary and asks to apply it.
  • Without --url it works on the data of a stopped reportd, starting renderd itself as reportd would. It refuses while reportd answers on its address: use --url and the code then.
  • --yes takes every answer from the flags (--admin-user, default admin; --admin-password-file, required; --admin-mfa; --licence-file, without which reportd is Community; --public-url; --environments; --update-check=false, which turns the version check off) and asks nothing. The password file isn't kept or changed.
  • Exit codes: 0 when done, 2 when a check fails (each failure printed, nothing applied), 1 for anything else.

reportd init-config still writes a whole config file, with an administrator's password, for installs that don't want setup mode.

If something goes wrong ​

  • The code is lost: it is in dataDir/setup-code and in every start's log until setup is done.
  • A check fails on storage or the engine: fix the config file or the environment and start reportd again; those steps have nothing to answer differently.
  • Starting over: before anyone signs in, stop reportd and delete dataDir (or the volume). After that, setup is done for good; manage users in the studio.

© Frontforge Pty Ltd