Setting up a server
You need: a Hetzner server running Debian 12 or Ubuntu 24.04 (x86 or Arm), a domain whose DNS you control, a way to send mail (a Scaleway project with Transactional Email, or an SMTP account), and an EU object storage bucket.
DNS. Point the domain's A (and AAAA) record at the server. Caddy needs this to get a certificate. Check it from your own machine with
dig +short reports.example.org. A fresh Debian has nodig(dig: command not found): usehost reports.example.orgorgetent hosts reports.example.orginstead, which every machine has, orsudo apt install dnsutilsto getdig. Either way you should see the server's address and nothing else.If people will also type
www.(or any other name), point that name here too and list it inSITE_ALIASESin/etc/reportlog/deploy.env. Caddy then gets it a certificate and sends it to the site's address. A name that points here without being listed gets a TLS error, not the site.- Firewall. In the Hetzner Cloud console, allow inbound 22, 80 and 443 (443/udp too, for HTTP/3) and nothing else. PostgreSQL listens on no TCP port at all, so there is nothing else to protect, but a firewall at the edge costs nothing.
Install.
git clone https://github.com/munsdev/reportlog.git /root/reportlog sudo /root/reportlog/deploy/install.shA private repository needs a credential for that
git cloneand for every laterreportlog updatesandreportlog deploy. It is root's credential, set up in root's own git configuration (a deploy key in/root/.ssh, or a token in/root/.git-credentials), because those commands run as root. Thereportloguser, which runs the website, never holds it, and a credential that is missing or has expired shows up in the doctor as a failed fetch, not as a network fault.It turns on unattended security updates and installs PostgreSQL 16 (from the PostgreSQL project's repository, socket only), Node at the exact version in
deploy/versions.conf(refused unless its SHA-256 matches), and Caddy. It creates thereportloguser, the database and role (peer authentication: no password exists to leak), and writes/etc/reportlog/reportlog.envfrom.env.example. It is safe to run again, and never overwrites the settings file.- Settings: answer the installer's questions. Nobody edits the settings
file by hand.
install.shmakes the keys a machine can make (CONTACT_KEY,FILES_KEY,DOOR_KEY, the transparency log's deploy key), setsTRUST_PROXY=1(Caddy is one proxy in front), and then asks, one at a time, for what only you know: the site's address, how mail is sent (the sending address, then an SMTP server and its sign-in, or Scaleway's project ID and secret key), who gets alerts, the off-site backup bucket and its upload-only key, storage for reporters' files, and where the transparency log is pushed. Keys and passwords are not shown while you type them. Enter skips a question; it ends by naming what is still empty, and running it again asks only that. Have the accounts below ready (Email, Off-site backups) before you start, or come back to them. - Deploy.
sudo reportlog deployThen set the site password:sudo reportlog site-password(it asks twice and shows nothing as you type). Open the site, enter that password, and the setup wizard makes you the owner and asks whether to keep the password. The wizard refuses to run without one, so a stranger who finds a fresh install cannot seat themselves as its owner. The same command is the way back in if the password is ever lost. - Check.
sudo reportlog doctor, thensudo reportlog mail-test you@example.organd look for the message, including in the spam folder. - Copy the settings file off the server, once, to wherever you keep
secrets. Backups deliberately do not include it (it holds keys, and a
backup that carries its own keys protects nothing). Above all
CONTACT_KEYandFILES_KEY: see below. - Optional: error tracking, with Bugsink on this server
(
sudo /root/reportlog/deploy/install-bugsink.sh, below).
Keys and secrets#
Keys, passwords and tokens are part of setting up a server, never part of
the repository (docs/decisions.md). On a server they are in
/etc/reportlog/reportlog.env (root:reportlog, 0640) and nowhere else: the
API, every job and every deploy step read that one file
(node --env-file=/etc/reportlog/reportlog.env), and .env.example in the
repository has every one of them blank.
| Setting | Where it comes from |
|---|---|
CONTACT_KEY, FILES_KEY | made by install.sh (32 random bytes); never changed, only rotated |
DOOR_KEY | made by install.sh (32 random bytes); safe to replace at any time |
TWO_FACTOR_KEY | made by install.sh (32 random bytes); a new one resets staff apps |
TRANSPARENCY_LOG_SSH_KEY | a key file made by install.sh; its public half is shown to add |
SMTP_PASS | asked by install.sh when an SMTP server is given |
SCALEWAY_SECRET_KEY | asked by install.sh, from the Scaleway console |
BACKUP_S3_ACCESS_KEY_ID, BACKUP_S3_SECRET_ACCESS_KEY | asked by install.sh, from the storage provider (upload-only key) |
S3_ACCESS_KEY, S3_SECRET_KEY | asked by install.sh, once a files provider is chosen |
TRANSPARENCY_LOG_REMOTES | asked by install.sh (an https address may carry a token) |
ERROR_TRACKING_DSN | written by install-bugsink.sh |
CONTACT_KEY_PREVIOUS | only while rotating the contact key, by a person (below) |
apps/api/test/unit/secrets.test.ts holds the code to this table. The
one exception to "one file" is Bugsink's own key, which lives in
/etc/bugsink/bugsink.env: Bugsink is a second application and must not be
able to read the archive's keys.
CI scans every commit of the repository for keys (gitleaks, pinned by
version and checksum, with .gitleaks.toml). If it ever finds one, the key
is leaked whatever happens next: rotate it first, then remove it.
The contact key#
Every reporter's address is encrypted under a per-report key, and those
keys are wrapped by CONTACT_KEY (apps/api/src/filing/contactKeys.ts).
install.sh makes it, from 32 random bytes, the first time it writes the
settings file. Nobody chooses or types it.
- Back it up separately. It is not in the database backups, on purpose:
a dump and the key that opens the addresses in it must not travel
together. Keep a copy off the server and away from the backups, in a
password manager the operators share, for instance:
sudo grep ^CONTACT_KEY= /etc/reportlog/reportlog.env. - Never change it by accident. A different key makes every stored
address unreadable. The first deploy records the key's fingerprint
(
/var/lib/reportlog/contact-key.sha256). From then on, a deploy with a different key stops before switching, and the doctor fails. If that happens, put the original key back.install.shnever makes a new key on a server that has recorded one. To change it on purpose, rotate it (below). - Lose it and you lose the addresses. The reports themselves are unaffected: they never contain an address.
Rotating the contact key#
For when the key may have been seen by somebody it should not have been, or an operator who held it leaves. The site keeps running throughout.
- Make a new key (
openssl rand -base64 32) and keep a copy off the server. - In
/etc/reportlog/reportlog.env, move the current key toCONTACT_KEY_PREVIOUS=and put the new one inCONTACT_KEY=. Deploy (or restart the API). The deploy's check lets this through because the key inCONTACT_KEY_PREVIOUSis the recorded one; any other change is still refused. With both keys the site writes everything new under the new key and still reads the old. sudo reportlog contact-key rotate. In one transaction it re-wraps every report's key under the new key and re-computes the digests that find a reporter's reports; then it records the new key's fingerprint. IfCONTACT_KEY_PREVIOUSis not the key the rows are under, it stops and changes nothing. It is safe to run again. Erased reports stay erased: their keys are gone and nothing brings them back.- Remove
CONTACT_KEY_PREVIOUS=and restart the API. The doctor warns until you do. Destroy the old key's copies.
Every rotation is recorded in the database (contact_key_rotations, by
fingerprint, never the key). The code is apps/api/src/filing/rotateContactKey.ts.
Two-factor login#
Everybody with a role (the owner, administrators, access managers,
moderators, journalists and anybody in an organization) proves a second
factor after the emailed code: an authenticator app or a passkey (plan E,
decision E3). Staff sessions last 12 hours. Authenticator-app secrets are
encrypted under TWO_FACTOR_KEY, which install.sh makes. It is not the
contact key and has none of its rules: if it is lost or replaced, each
staff member sets their app up again after signing in with a passkey or a
recovery code, or after a reset. Passkeys and recovery codes are not under it.
The owner resets anybody else's second factor from the Access screen. The owner's own is reset only here, on the server:
sudo reportlog reset-2fa owner@example.org
It clears that person's authenticator app, passkeys and recovery codes and
signs them out everywhere. Their next sign-in, after the emailed code, sets
a new one up. Each reset is recorded in the role audit, which nobody can
edit. The code is apps/api/src/identity/reset-two-factor.ts.
Email#
One provider, either Scaleway Transactional Email or an SMTP server, never
both (EMAIL_TRANSPORT). The installer asks for an SMTP server first; press
Enter there to use Scaleway instead.
- SMTP (Proton Mail, say):
SMTP_HOST(smtp.protonmail.ch),SMTP_PORT(587 for STARTTLS, 465 for TLS),SMTP_USER(for Proton, the sending address) andSMTP_PASS(for Proton, an SMTP token made in its settings, not the account password). The sending domain must be one the provider has verified for you. - Scaleway: in the Scaleway console, add and verify the sending domain under Transactional Email, publish the SPF, DKIM and DMARC records it shows you, and create an API key whose IAM policy allows Transactional Email in that project.
Either way, mail from a domain without SPF, DKIM and DMARC records is usually
accepted and then filed as junk, so mail-test succeeding is not the end of
it: check the message arrives.
Error tracking (Bugsink)#
Optional, and off until you set it up. With it on, the API's unexpected
errors, a scheduled job that crashes, and errors in visitors' browsers
arrive in Bugsink, on this same server (the
owner's decision, docs/decisions.md item 13).
- A domain for it, such as
bugsink.reports.example.org, with its DNS (A and AAAA) pointed at this server like the site's. Install it:
sudo /root/reportlog/deploy/install-bugsink.shIt asks for the domain (suggesting
bugsink.<the site's domain>), then installs Bugsink at the version indeploy/versions.confinto/opt/bugsink-<version>, fromdeploy/bugsink/requirements.txt, where every file pip may install is pinned by SHA-256 (downloaded from PyPI). It runs as its ownbugsinkuser with its own database (SQLite files in/var/lib/bugsink, not the archive's PostgreSQL) and its own key (/etc/bugsink/bugsink.env, made here). It asks for an email address and password for Bugsink's own sign-in, makes a project called "ReportLog", and writesERROR_TRACKING_DSNinto/etc/reportlog/reportlog.env, pointing athttp://<key>@127.0.0.1:8000/<project>: the API sends to the local port, so its events never leave the machine. It starts the servicesbugsink(on 127.0.0.1:8000, no access log) andbugsink-snappea(its background worker), restarts the API, and adds the domain to Caddy, which every later deploy keeps (BUGSINK_DOMAINin/etc/reportlog/deploy.env).- Sign in at
https://<the domain>.
Set ERROR_TRACKING_ENVIRONMENT=staging on a server that is not the real
one. Jobs pick up the DSN the next time they run.
Bugsink is a second application with its own login on the archive's
server, so it is kept apart: it cannot read /etc/reportlog, its units are
confined like the archive's, it does not record visitors' addresses
(USE_X_REAL_IP = False; Caddy keeps no access log for it either), it
sends no email, and its anonymous daily report to bugsink.com is turned
off (deploy/bugsink/bugsink_conf.py). An error is kept 30 days. Its
database is not in the backups: it holds errors to fix, not a record.
Upgrading Bugsink: change the version in deploy/bugsink/requirements.in
and BUGSINK_VERSION in deploy/versions.conf, regenerate
requirements.txt (the command is in requirements.in), merge, then run
install-bugsink.sh again from an updated checkout. Its services apply
Bugsink's own migrations when they start.
Moving Bugsink off this server later needs only a new DSN: run Bugsink
elsewhere, make a project, put its DSN in ERROR_TRACKING_DSN, restart the
API, then systemctl disable --now bugsink bugsink-snappea here and empty
BUGSINK_DOMAIN in deploy.env.
What an event carries is an allowlist (packages/contracts/src/telemetry.ts):
the error's type and message, its stack, the route's pattern
(/api/reports/:ref, never the address) and the release. Never an IP
address, a page's address (an address can carry a token), a request body,
headers, cookies, who was signed in or what they did before. URLs, email and
IP addresses and anything that looks like a token are cut out of the message
too. Refusals (a 404, a wrong password, a bad form) are not errors and are
not sent.
Visitors' browsers never talk to Bugsink. The website loads nothing for
this until an error happens; then it asks this site whether tracking is on,
and if so posts the error to this site (/api/telemetry/errors). The server
cleans it again, because a browser is not trusted to have, and passes it on
with its own DSN. At most 30 website errors a minute are passed on, so a
stranger cannot flood your Bugsink through the site. The site's content
security policy still allows no other host.
With ERROR_TRACKING_DSN empty, nothing is sent anywhere and the relay
answers that error tracking is off.
Off-site backups#
- An encryption key, made somewhere that is not the server:
age-keygen -o reportlog-backup-key.txt. Keep the file (the private key) in two safe places. Put the public key it prints (age1…) inBACKUP_AGE_RECIPIENTS. Add a second person's public key, separated by a space, if more than one person should be able to restore. - A bucket in EU object storage: Hetzner Object Storage
(
https://fsn1.your-objectstorage.com, regionfsn1) or Scaleway Object Storage (https://s3.nl-ams.scw.cloud, regionnl-ams), for example. - A key for the server that can upload and nothing else: no read, no list, no delete. Somebody who takes over the server can then add files to the bucket but cannot empty it, and that is the moment a backup is for.
- A lifecycle rule on the bucket that expires objects under
reportlog/after the period you want to keep (90 days, say). The server never deletes off-site copies; the bucket does. - The five
BACKUP_S3_settings, thensudo reportlog backupandsudo reportlog doctor.
Checking file storage#
Reporters' files (evidence) live in three buckets, separate from the backup
bucket: staging, evidence and renditions (FILES_STORAGE=s3 and the S3_
settings, explained in the settings file). Once you have chosen a provider,
and before the site takes anybody's files, run the check once against it, on
the server:
cd /srv/reportlog/current
sudo -u reportlog /usr/local/bin/node --env-file=/etc/reportlog/reportlog.env \
apps/api/src/files/storage-check-cli.ts
It writes a small object to each bucket, reads it back whole and as a range,
deletes it, and checks it is gone. It leaves nothing behind. Every line
should start with ok:
ok staging: write, read, range, delete, refuses an unsigned read
ok evidence: write, read, range, delete, refuses an unsigned read
ok renditions: write, read, range, delete, refuses an unsigned read
| It says | Usually |
|---|---|
Storage is not configured: … | the setting it names is empty |
failed: 404 … NoSuchBucket | that bucket's name is wrong, or it was made in another region |
failed: 403 … SignatureDoesNotMatch / …Denied | the key or secret is wrong, or the key may not use that bucket |
fetch failed (ENOTFOUND) | S3_ENDPOINT names a host that does not exist |
fetch failed (ECONNREFUSED) or a certificate | the endpoint is wrong, or not reachable from the server |
answers a read with no signature | the bucket is public: make it private in the provider's panel |
… is wrapped in quotes / … a space | .env holds the value with quotes or spaces: write it bare |
cannot be used with virtual-hosted addressing | rename the bucket without dots or capitals, or use path style |
The files key needs read, write and delete on these three buckets (unlike
the backup key, which may only upload). The check has been run against
moto, a local S3-compatible server, by apps/api/test/unit/deploy-storage-check.test.ts
on every CI run, with path-style addressing. Virtual-hosted addressing
(S3_ADDRESSING=virtual) is tested only against the repository's own
stand-in (apps/api/test/unit/files-storage.test.ts): if the provider
needs it, this check is the first real thing that will run it.
Every setting, by name#
.env.example is the list; this is what each setting is for, so nothing in
the settings file is a mystery. The installer fills in the ones it can and
asks for the ones only you know (above), and sudo reportlog doctor names
anything still missing. A server installed before DOOR_KEY and
TWO_FACTOR_KEY existed has neither: the doctor warns, and running
/root/reportlog/deploy/install.sh again adds both and changes nothing else
in the file. A server's other settings, the keys, email, error tracking and
backups, are explained in their own sections above.
| Setting | What it does |
|---|---|
DATABASE_URL | The database. The installer writes it (a socket, no password). |
TEST_DATABASE_URL | Development only: where the test suite makes throwaway databases. Never on a server. |
HOST, PORT | Where the API listens. Leave at 127.0.0.1 and 3000: only Caddy is in front. |
LOG_LEVEL | How much the API logs. Logs never hold an address or a full link. |
PUBLIC_REF_PREFIX | The letters every public reference starts with (RL-). Sealed into every report: chosen once. |
FILING_SENDS_PER_CLIENT | How many confirmation emails one visitor may ask for in 15 minutes. |
DOOR_SUBMITS_PER_MINUTE, DOOR_SUBMITS_PER_HOUR | Reports and tips one network address may send per minute and per hour (6 and 60). |
DOOR_REQUESTS_PER_MINUTE | Requests of any kind one address may make per minute (600), so reading stays fast in a flood. |
FILING_CONFIRMS_PER_CLIENT | How many times one visitor may open or use confirmation links in 15 minutes. |
SITE_ORIGIN | The address people reach the site at. Every email link and Caddy's certificate use it. |
SEARCH_ENGINES | on (unset) or off. Off on a test server: robots.txt then asks every search engine to stay out. |
ATTACHMENTS_ENABLED | Whether files are taken until an administrator says otherwise. install.sh writes false. |
CLAMAV_ENABLED | Scan each file with ClamAV first (needs clamd). |
FILES_DIR, FILES_INLINE_WORKER | Development only: where disk storage keeps files, and running the media worker inside the server. |
FILES_STAGING_QUOTA_REPORTS | How many reports' worth of files one address may have waiting. 0 is no limit. |
S3_REGION | The files storage region. The installer reads it off the endpoint where it can. |
S3_BUCKET_STAGING, S3_BUCKET_EVIDENCE, S3_BUCKET_RENDITIONS | The three buckets for files not yet sent, files with a report, and re-encoded copies. |
EMAIL_TRANSPORT | off, scaleway or smtp: one provider, never both. The installer turns it on once it can send. |
EMAIL_FROM_ADDRESS, EMAIL_FROM_NAME | The sender, on a domain your mail provider has verified. |
SCALEWAY_PROJECT_ID, SCALEWAY_REGION | The Scaleway project and region (fr-par) mail goes through. |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE | For smtp. Proton Mail: smtp.protonmail.ch, 587, the sending address, an SMTP token. |
MAIL_OUTBOX | Browser tests only: write each email as a file. Never on a server. |
LIST_PERSONAL_DAYS, LIST_ERASURE_LINK_DAYS | How long a list keeps the personal half of an entry (with its links), and an erasure link. |
LIST_KNOWN_HOSTS | Link hosts a moderator knows; others are marked for a look. |
BACKUP_DIR, BACKUP_KEEP, BACKUP_MAX_AGE_HOURS | Where local dumps go, how many to keep, and how old the newest may be before the doctor fails it. |
BACKUP_S3_ENDPOINT, BACKUP_S3_REGION, BACKUP_S3_BUCKET, BACKUP_S3_PREFIX | The off-site bucket. The installer reads the region off the endpoint where it can. |
STATE_DIR | Where jobs record what they last did, for the doctor. |
TRANSPARENCY_LOG_DIR, TRANSPARENCY_LOG_BRANCH | The checkout of the transparency log on this server, and its branch. |
TRANSPARENCY_LOG_AUTHOR_NAME, TRANSPARENCY_LOG_AUTHOR_EMAIL | Who the log's commits are by. |
TSA_URL | The RFC 3161 timestamp authority. Unset, DFN's, in Germany. |
PRESS_DIR | A folder with a press pack built ahead of time. Unset, the press page says there is none. |