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, assetupCode=…:docker compose logs reportd | grep setupCode, orkubectl 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/v1request, the MCP endpoint and report links answer503 setup-required; the studio goes to/setup.Wrong codes count in the
signinrate-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/setupanswers 404 from then on.
The steps
The wizard and reportd setup ask the same steps and run the same checks.
- 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. - Licence: paste the licence or choose its file. Every install needs one: the free Community licence, from https://myaccount.frontforge.com/community (licence.md), or a paid one. The step says what the licence includes. A Community licence is used under the Frontforge Report Server Community Licence: the step shows it, links to it on its own page (
GET /v1/terms?format=text), and goes on only once I accept the Frontforge Report Server Community Licence is ticked. A paid licence has its own agreement. A licence that doesn't verify, hasn't started or has lapsed is an error. When thelicencesetting fixes one, the step only shows it. When the configuration turns on what needs a paid licence (SSO providers, Postgres state or separate renderd instances), the step lists those settings and is an error until the licence grants them (licence.md). - 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
httpon 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 writesupdates.check: false. - Environments: their names and promotion order, by default
dev, test, uat, prod. They are hard to change once templates exist. Without a licence withenvironments, more than one is a warning: only the first is usable for publishing, so Community wants one. - 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. - Engine: renderd answers, its fonts load, and a test render of a small built-in page shows the result.
- 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.
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.jsononstate.driver: file, Postgres onpostgres), 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.environmentsandauth.mfa. reportd reads it over the config file and under the environment (docker.md). A setting the config file or aREPORTD_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 installwould: intodataDir/licence, or Postgres onpostgres. - The audit log gets
setup.complete, with the administrator's name and the settings written, andlicence.install <id>for the licence, withterms.accept Frontforge Report Server Community Licence <version>for a Community 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
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
reportd setup --yes --admin-password-file ./pw --licence-file ./community.licence --accept-terms- 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. With a Community licence, it offers to show the Community licence's terms and asks whether you accept them.
- Without
--urlit works on the data of a stopped reportd, starting renderd itself as reportd would. It refuses while reportd answers on its address: use--urland the code then. --yestakes every answer from the flags (--admin-user, defaultadmin;--admin-password-file, required;--admin-mfa;--licence-file, required: the Community licence or a paid one;--accept-terms, required with a Community licence, which accepts its terms;--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-codeand 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.