Settings
Every setting a ReportLog server reads, with what it does, read from the settings file the installer starts from.
A server's settings live in /etc/reportlog/reportlog.env (owned by root, readable by the reportlog group) and nowhere else. The installer writes it from .env.example in the repository, makes the keys a machine can make, and asks for the rest. Nobody edits it by hand to set up a site; to change one value later, edit it there and restart (sudo systemctl restart reportlog-api) or deploy. The application checks every value when it starts and names anything wrong, and sudo reportlog doctor says what is still missing.
Keys, passwords and tokens are never in the repository: every one is blank in .env.example. Keep a copy of the settings file off the server. Backups deliberately leave it out, because it holds the keys.
This page is read from .env.example itself, so it lists exactly what the code reads. "Example" values are placeholders or defaults, not recommendations.
The server
| Setting | Meaning |
|---|---|
DATABASE_URL | |
TEST_DATABASE_URL | The database the test suite creates throwaway databases beside. Not used on a server. |
HOSTPORTexample: 127.0.0.1 | Where the API listens. Keep 127.0.0.1 on a server: Caddy is the only thing in front of it. |
LOG_LEVELexample: info | fatal, error, warn, info, debug, trace or silent. |
PUBLIC_REF_PREFIXexample: RL- | The prefix of every public reference (RL-1234). Sealed into every report, so it is chosen once and never changed. |
FILING_SENDS_PER_CLIENTexample: 20 | Reports one visitor may send for confirmation in 15 minutes. Anybody can make the site email any address they type, so keep this low. |
FILING_CONFIRMS_PER_CLIENTexample: 60 | Times one visitor may open or use confirmation links in 15 minutes. |
SITE_ORIGIN | The address people reach the site at. Every link in every email is built from it, and Caddy gets its certificate for this domain. Unset, it is the development website (http://127.0.0.1:5173); the doctor fails a server left like that. |
TRUST_PROXYexample: 0 | How many proxies stand in front of the API. 1 on a server (Caddy), so the sign-in limits count each visitor and not the whole site as one. 0 when nothing is in front, as in development. |
SEARCH_ENGINESexample: on | Whether search engines are invited in (robots.txt and the sitemap). Set it to off on a test server, so it never shows up in search results in place of the real site. A site behind its password is closed either way. |
The reporters' contact key
| Setting | Meaning |
|---|---|
CONTACT_KEY | The key every reporter's address is encrypted under: 32 random bytes, base64 (openssl rand -base64 32). deploy/install.sh makes one on a server. Without it the site takes no reports. NEVER just change it on a running archive: every stored address would become unreadable. Rotate it instead (CONTACT_KEY_PREVIOUS below, and deploy/README.md). It is not in the database backups, on purpose: keep a copy somewhere that is not the server and not beside the backups (deploy/README.md). |
CONTACT_KEY_PREVIOUS | Only while rotating CONTACT_KEY: the key being rotated away from, with the new one in CONTACT_KEY. Removed once reportlog contact-key rotate has run (deploy/README.md, "Rotating the contact key"). |
FILES_KEY | Files (photos, video, audio, documents). The key each file's own key is wrapped under: 32 random bytes, base64, and NOT the same as CONTACT_KEY. Never change it on a running archive. Without it no file is taken. |
DOOR_KEY | At the door (reports and tips). The key puzzles and form start tokens are signed with: 32 random bytes, base64. Nothing signed with it outlives a day, so a new one costs only the forms open at that moment. Made by install.sh; left empty, the server makes one in memory each time it starts. |
DOOR_SUBMITS_PER_MINUTEDOOR_SUBMITS_PER_HOURDOOR_REQUESTS_PER_MINUTEexample: 6 | Reports and tips one network address may send, per minute and per hour, and requests of any kind per minute. Counted under a hash whose key changes daily and is never written down. Start low and tune in the flood rehearsal. |
Two-factor login
| Setting | Meaning |
|---|---|
TWO_FACTOR_KEY | Staff authenticator-app secrets are encrypted under it: 32 random bytes, base64, and NOT the same as CONTACT_KEY. deploy/install.sh makes one. Losing or replacing it means every staff member sets their app up again (passkeys and recovery codes still work). Without it the app cannot be set up; passkeys still can. |
FILES_STORAGEFILES_DIRexample: disk | disk (development) or s3 (production: any S3-compatible storage in the EU). |
FILES_INLINE_WORKERexample: true | Development only: run the media worker inside the server. |
ATTACHMENTS_ENABLED | Whether files are taken when an administrator has not said (true or false). A new server is installed with this set to false (decision 38): a filing that carries a file is then refused, and an administrator switches uploads on. |
CLAMAV_ENABLEDexample: false | Scan each file with clamdscan first (needs a running clamd). |
FILES_STAGING_QUOTA_REPORTSexample: 3 | How many reports' worth of files one address may have waiting at once. 0: no limit. |
S3_ENDPOINTS3_REGIONS3_ACCESS_KEYS3_SECRET_KEYS3_BUCKET_STAGINGS3_BUCKET_EVIDENCES3_BUCKET_RENDITIONSS3_ADDRESSING | For FILES_STORAGE=s3: |
| Setting | Meaning |
|---|---|
EMAIL_TRANSPORTexample: off | off: send nothing; each message goes to the service's standard error instead, so a fresh install can still sign its operator in. The doctor fails a server left on it. scaleway: send through Scaleway Transactional Email. smtp: send through an SMTP server (Proton Mail, say). One or the other. |
EMAIL_FROM_ADDRESSEMAIL_FROM_NAMEexample: reports@example.org | The sender. Must be on a domain verified with your provider, with SPF, DKIM and DMARC records published, or mail is accepted and then filed as junk. |
SCALEWAY_SECRET_KEYSCALEWAY_PROJECT_ID | From the Scaleway console: an API key with Transactional Email permission (IAM), and the project the sending domain belongs to. |
SCALEWAY_REGIONEMAIL_TRANSPORTexample: fr-par | Transactional Email is served from Paris. |
SMTP_HOSTSMTP_PORTSMTP_USERSMTP_PASSexample: smtp.protonmail.ch | smtp.protonmail.ch, 587, your custom-domain address, and an SMTP token (Settings > IMAP/SMTP > SMTP tokens), never the account password. |
SMTP_SECUREexample: false | Direct TLS. Unset: on for port 465, STARTTLS otherwise. |
MAIL_OUTBOXexample: /tmp/reportlog-outbox | For the browser tests only: write each email as a file in this directory instead of sending it. Never on a server. |
OPS_ALERT_EMAILexample: ops@example.org | Who is emailed when a scheduled job fails. Leave empty and only the doctor will tell you. |
ADMIN_EMAILexample: office@example.org | Where a list's new entries are announced when the list names no address of its own. |
Error tracking
| Setting | Meaning |
|---|---|
ERROR_TRACKING_DSN | A Bugsink project's DSN. Empty: no error tracking at all. Set: the server sends its unexpected errors there, and relays the website's (visitors' browsers only ever talk to this site). Events carry no IP address, no address of a page and no request body. deploy/install-bugsink.sh sets it to Bugsink on this server (http://<key>@127.0.0.1:8000/<project>). |
ERROR_TRACKING_ENVIRONMENTexample: production | Shown beside each event, to tell a staging server from the real one. |
Lists
| Setting | Meaning |
|---|---|
LIST_PERSONAL_DAYSexample: 365 | Days the personal half of a list entry is kept before the lists sweep erases it, or "never" (then only the person's own erasure link removes it). Unset: 365. |
LIST_ERASURE_LINK_DAYSexample: 365 | Days an erasure link lasts where nothing is erased on its own. |
LIST_KNOWN_HOSTS | Link hosts a moderator knows, comma-separated; others are marked for a look. |
Backups
| Setting | Meaning |
|---|---|
BACKUP_DIRBACKUP_KEEPBACKUP_MAX_AGE_HOURSexample: /var/backups/reportlog | Local dumps: where, how many to keep, and how old the newest may be before the doctor calls it a failure. |
STATE_DIRexample: /var/lib/reportlog | Where jobs record what they last did, for the doctor. |
BACKUP_AGE_RECIPIENTSexample: age1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq | Off-site copies are encrypted to these age public keys before they leave the server (make one with age-keygen on a machine that is NOT the server, and keep the private key there and somewhere safe). Space or comma separated, so a second person's key can be added. |
BACKUP_S3_ENDPOINTBACKUP_S3_REGIONBACKUP_S3_BUCKETBACKUP_S3_PREFIXBACKUP_S3_ACCESS_KEY_IDBACKUP_S3_SECRET_ACCESS_KEY | S3-compatible object storage in the EU, e.g. Hetzner Object Storage (https://fsn1.your-objectstorage.com, region fsn1) or Scaleway Object Storage (https://s3.nl-ams.scw.cloud, region nl-ams). Give the key permission to upload and nothing else, and expire old copies with the bucket's lifecycle rules (deploy/README.md). All five, or none. |
The daily anchor
| Setting | Meaning |
|---|---|
TRANSPARENCY_LOG_DIRexample: /var/lib/reportlog/transparency-log | The checkout of the public transparency log on this server. Under STATE_DIR on a server: it is the only path the job's unit may write. Set here rather than left commented: install.sh writes the settings file from this one and asks nothing about it, so a commented default left every server's daily anchor failing with "TRANSPARENCY_LOG_DIR is not set". |
TRANSPARENCY_LOG_REMOTES | Where the log is pushed: git addresses, comma-separated, each pushed on its own. An ssh address uses the key below (a deploy key with WRITE access); an https one may carry its token. Secrets: never logged. For example git@github.com:example/reportlog-transparency-log.git |
TRANSPARENCY_LOG_SSH_KEYTRANSPARENCY_LOG_BRANCHexample: /var/lib/reportlog/transparency-log-key | The deploy key's private half: a path, made by deploy/install.sh. |
TRANSPARENCY_LOG_AUTHOR_NAMETRANSPARENCY_LOG_AUTHOR_EMAILexample: ReportLog anchor | Who the log's commits are by. |
TSA_URL | The RFC 3161 timestamp authority. Unset: DFN's, in Germany. |
ANCHOR_MAX_AGE_HOURSexample: 36 | Hours after which the doctor calls the newest anchor stale. |
The press pack
| Setting | Meaning |
|---|---|
PRESS_DIRexample: /var/lib/reportlog/press | A folder holding manifest.json and the documents it lists, built ahead of time. Unset, the press page says no pack has been built. ReportLog ships none. |