ReportLog
Documentation menu

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

SettingMeaning
DATABASE_URL
TEST_DATABASE_URLThe database the test suite creates throwaway databases beside. Not used on a server.
HOST
PORT
example: 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_LEVEL
example: info
fatal, error, warn, info, debug, trace or silent.
PUBLIC_REF_PREFIX
example: RL-
The prefix of every public reference (RL-1234). Sealed into every report, so it is chosen once and never changed.
FILING_SENDS_PER_CLIENT
example: 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_CLIENT
example: 60
Times one visitor may open or use confirmation links in 15 minutes.
SITE_ORIGINThe 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_PROXY
example: 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_ENGINES
example: 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

SettingMeaning
CONTACT_KEYThe 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_PREVIOUSOnly 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_KEYFiles (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_KEYAt 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_MINUTE
DOOR_SUBMITS_PER_HOUR
DOOR_REQUESTS_PER_MINUTE
example: 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

SettingMeaning
TWO_FACTOR_KEYStaff 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_STORAGE
FILES_DIR
example: disk
disk (development) or s3 (production: any S3-compatible storage in the EU).
FILES_INLINE_WORKER
example: true
Development only: run the media worker inside the server.
ATTACHMENTS_ENABLEDWhether 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_ENABLED
example: false
Scan each file with clamdscan first (needs a running clamd).
FILES_STAGING_QUOTA_REPORTS
example: 3
How many reports' worth of files one address may have waiting at once. 0: no limit.
S3_ENDPOINT
S3_REGION
S3_ACCESS_KEY
S3_SECRET_KEY
S3_BUCKET_STAGING
S3_BUCKET_EVIDENCE
S3_BUCKET_RENDITIONS
S3_ADDRESSING
For FILES_STORAGE=s3:

Email

SettingMeaning
EMAIL_TRANSPORT
example: 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_ADDRESS
EMAIL_FROM_NAME
example: 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_KEY
SCALEWAY_PROJECT_ID
From the Scaleway console: an API key with Transactional Email permission (IAM), and the project the sending domain belongs to.
SCALEWAY_REGION
EMAIL_TRANSPORT
example: fr-par
Transactional Email is served from Paris.
SMTP_HOST
SMTP_PORT
SMTP_USER
SMTP_PASS
example: 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_SECURE
example: false
Direct TLS. Unset: on for port 465, STARTTLS otherwise.
MAIL_OUTBOX
example: /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_EMAIL
example: ops@example.org
Who is emailed when a scheduled job fails. Leave empty and only the doctor will tell you.
ADMIN_EMAIL
example: office@example.org
Where a list's new entries are announced when the list names no address of its own.

Error tracking

SettingMeaning
ERROR_TRACKING_DSNA 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_ENVIRONMENT
example: production
Shown beside each event, to tell a staging server from the real one.

Lists

SettingMeaning
LIST_PERSONAL_DAYS
example: 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_DAYS
example: 365
Days an erasure link lasts where nothing is erased on its own.
LIST_KNOWN_HOSTSLink hosts a moderator knows, comma-separated; others are marked for a look.

Backups

SettingMeaning
BACKUP_DIR
BACKUP_KEEP
BACKUP_MAX_AGE_HOURS
example: /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_DIR
example: /var/lib/reportlog
Where jobs record what they last did, for the doctor.
BACKUP_AGE_RECIPIENTS
example: 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_ENDPOINT
BACKUP_S3_REGION
BACKUP_S3_BUCKET
BACKUP_S3_PREFIX
BACKUP_S3_ACCESS_KEY_ID
BACKUP_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

SettingMeaning
TRANSPARENCY_LOG_DIR
example: /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_REMOTESWhere 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_KEY
TRANSPARENCY_LOG_BRANCH
example: /var/lib/reportlog/transparency-log-key
The deploy key's private half: a path, made by deploy/install.sh.
TRANSPARENCY_LOG_AUTHOR_NAME
TRANSPARENCY_LOG_AUTHOR_EMAIL
example: ReportLog anchor
Who the log's commits are by.
TSA_URLThe RFC 3161 timestamp authority. Unset: DFN's, in Germany.
ANCHOR_MAX_AGE_HOURS
example: 36
Hours after which the doctor calls the newest anchor stale.

The press pack

SettingMeaning
PRESS_DIR
example: /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.

See this page's source