Standing up ReportLog

Start here if you have just rented a server and are looking at a control panel wondering what to do. If you already have a root shell open, skip to Before you start.

If you do not have an SSH key

A key is a pair of files on your own machine. The public half goes to the server, the private half never leaves you, and together they replace typing a password. Make one:

ssh-keygen -t ed25519

ssh-keygen -t ed25519

Press Enter at every prompt to accept the defaults. A passphrase is optional and worth having. Then print the public half, which is the part you paste into Hetzner:

cat ~/.ssh/id_ed25519.pub

type $env:USERPROFILE\.ssh\id_ed25519.pub

Connecting

Then, replacing the address with your server's:

ssh root@203.0.113.10

The first five minutes on a new box

Everything from here runs on the server, in that SSH window, not on your own machine.

Update what is installed. On a fresh image this usually has something to do, and it is the one command that most often asks a question:

apt update && apt upgrade -y

Set the server's name, so the prompt and the logs say what this machine is:

hostnamectl set-hostname reports.example.org

Turn on the firewall. Do the SSH line first — enabling the firewall without it locks you out of your own server:

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable
ufw status

adduser casey
usermod -aG sudo casey
rsync --archive --chown=casey:casey ~/.ssh /home/casey

Four things, in this order. Two of them take longer to arrange than the install does. The instructions are right here rather than further down the page — work through these, then go straight to the install.

1 · A server

Any Linux box you have root on, from any host — nothing here is specific to one provider. Use Debian 12 or Ubuntu 22.04 / 24.04: those are the tested ones, and the only ones the install script installs packages for.

These were measured on 6 October 2026, on an idle instance with an empty archive. They are a floor, not a forecast.

Not needed, and deliberately: no Docker or container runtime, no Redis, queue or second service, and no build step — the frontend is served as it sits, so there is no toolchain to install.

2 · Point a hostname at the server

You need the server's public IP addresses. Your host shows them on the server's page; on the server itself:

curl -4 https://ifconfig.co    # IPv4, e.g. 203.0.113.10
curl -6 https://ifconfig.co    # IPv6, if the server has one

Find the right DNS editor first

DNS is edited wherever the domain's nameservers point, which is not always where you bought it. If you are not sure, ask the domain — run this on your own machine or on the server, it does not matter which:

dig +short NS example.org

“dig: command not found”? It is not installed by default on a fresh server or on Windows. Either install it — sudo apt install -y dnsutils on Debian or Ubuntu — or use what is already there: host -t NS example.org, or nslookup -type=NS example.org, which exists everywhere including Windows.

In that editor, create:

Name field conventions differ. Some editors want just reports, some want the whole reports.example.org, and some use @ for the bare domain. If yours shows existing records, copy the style they use.

Set a low TTL before you change anything if the record already exists: that is how long the old answer stays cached, and 300 seconds beats waiting out a day-long one. Then check, from your own machine and not from the server:

dig +short reports.example.org

3 · Somewhere to send mail from

Not optional. Signing in is a one-time code sent by email, so without working mail nobody can sign in at all — including you, and including the setup wizard at the end of the install. Reports cannot be confirmed either.

You need four values: an SMTP host, a port, a username and a password. The configure step asks for them, and the mail test after it sends a real message to prove they work.

Do not send mail from the server itself

A new server's own IP has no reputation, and mail from it is treated as spam by nearly everyone. You would be debugging deliverability instead of running an archive. Use a provider; the free tiers are far more than this needs.

Whichever you pick

1. Sign up and add your domain (or verify a single sender address, if you are only testing).
2. Add the SPF and DKIM DNS records it gives you, in the same DNS editor you used for the hostname above. They are usually one TXT record each. Without them your mail lands in spam.
3. Find the SMTP credentials page — sometimes called “SMTP”, sometimes “Sending”, sometimes “Integration”. Copy the host, the port, the username and the password.

https://fsn1.your-objectstorage.com

npm run storage-smoke

Reference rather than a to-do list: the steps install all of this. It is here so you can see what is about to change on the machine.

If you would rather have everything in place before you start, this is the whole package list for Debian and Ubuntu. The steps below install the same things one at a time, and running this first does not break them:

sudo apt update
sudo apt install -y postgresql nginx git curl ca-certificates \
                    ffmpeg libheif-examples poppler-utils

For anyone who has done this before. npm run doctor after each step says what is missing and prints the install command for your distribution.

Scripted

On Debian or Ubuntu, install.sh does every mechanical step and then stops and prints the three commands that need a person. Read the dry run first; there is no curl | bash form of this on purpose.

git clone --branch stable https://github.com/munsdev/reportlog.git
cd reportlog
sudo ./install.sh --dry-run          # prints every command, changes nothing
sudo ./install.sh --with-attachments

By hand

sudo -u postgres createuser reportlog --pwprompt
sudo -u postgres createdb reportlog -O reportlog

git clone --branch stable https://github.com/munsdev/reportlog.git /srv/reportlog
cd /srv/reportlog
npm ci --omit=dev
npm run doctor
npm run configure
npm run migrate
npm run set-curtain-password
npm run mail-test -- you@example.org

sudo ./contrib/install-units.sh
sudo certbot --nginx -d reports.example.org

Then merge contrib/nginx/reportlog.conf into the block certbot wrote, and open the site to run the wizard.

13 steps. Tick them off as you go — the ticks are kept in this browser, so you can close the tab, reboot the server, and come back to where you were.

1. A user, and somewhere to put it

   The application must not run as root. This makes a locked-down account to own it: no password, no shell login, nothing but the files it needs.

   About sudo in the commands below. If your prompt ends in # you are already root and sudo does nothing — harmless, so the commands keep it and work either way. If your prompt ends in $ you are a normal user and sudo is doing the work.

   sudo adduser --system --group --home /srv/reportlog reportlog

   what you should see

   Adding system user `reportlog' … and a couple of lines about a group and a home directory. It does not ask for a password, and it should not — nobody logs in as this account. Check it exists:

   id reportlog

   uid=… reportlog gid=… reportlog. If instead you get no such user, the command above did not run.

   Now become that user. Everything from here until the certificate step happens as reportlog, not as root:

   sudo -u reportlog -H bash
   cd /srv/reportlog

   what you should see

   Your prompt changes — often to a bare $ with no name on it, which looks like something broke and has not. You are in a second shell, inside the first one. Confirm who you are and where:

   whoami && pwd

   reportlog and /srv/reportlog. Typing exit leaves this shell and puts you back where you were — which is how you get to the sudo commands later on.

   If you want a different user or directory

   You can, but the shipped service files name this user and this path. Change them together and nothing else — contrib/install-units.sh, further down, does that substitution for you if you pass --dir and --user.

2. Node 22 or newer

   node --version

   you should see

   v22. or higher. Most distributions ship something older, so you probably need the next block.

   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt install -y nodejs

   Why not nvm, fnm or asdf

   Use a system package, not a version manager. nvm, fnm and asdf install Node inside a home directory and make it available only to shells that read a profile script. systemd does not read your shell profile. The service file names /usr/bin/node, and if Node is somewhere else the service fails with No such file or directory — which reads like a broken service file and is a missing interpreter.

   Check where yours is before the step that installs the units:

   command -v node

   If that is not /usr/bin/node, either install the system package or tell the unit installer with --node. It refuses a Node inside a home directory rather than writing a unit that cannot start.

3. PostgreSQL, a role and a database

   sudo apt install -y postgresql

   The role owns the database; the app connects as it. The first command asks you to choose a password, twice — keep it, you type it into the configure step.

   sudo -u postgres createuser reportlog --pwprompt
   sudo -u postgres createdb reportlog -O reportlog

   your connection string

   postgres://reportlog:the-password@localhost:5432/reportlog

   npm run doctor prints these two commands with your own names filled in. It will not run them for you: creating a role on somebody else's cluster is not a thing an install script should do unasked, and the authentication method your cluster uses is a decision only you can make.

4. Media tools, for photo, video and PDF uploads

   Skip this step if this deployment will never accept a file. Everything else works without it, and you can come back and do it later.

   sudo apt install -y ffmpeg libheif-examples poppler-utils

   what you should see

   All five on the path:

   for b in ffmpeg ffprobe heif-convert pdftoppm pdfinfo; do command -v $b || echo "MISSING $b"; done

   Five binaries from three packages, because the package names are not the binary names and they differ between distributions. If a line above says MISSING, the doctor prints the right command for the machine you are on.

   Not on Debian or Ubuntu, or a name is missing

   heif-convert is in libheif-examples on Debian and Ubuntu, libheif-tools on Fedora and Alpine, and libheif on Arch. pdftoppm and pdfinfo are both in poppler-utils.

   Two that catch people: Fedora and RHEL do not ship ffmpeg in their own repositories, so enable RPM Fusion first; and Alpine keeps libheif-tools in a repository that is commented out on some images.

   Virus scanning, which is off by default

   clamdscan is a sixth binary and a separate decision. Nothing uses it unless you set CLAMAV_ENABLED=true later, and it fails closed: if it is switched on and the binary is missing, uploads are left unprocessed rather than passed through unscanned.

   sudo apt install -y clamav-daemon

5. Get the code

   cd /srv/reportlog
   git clone --branch stable https://github.com/munsdev/reportlog.git .
   npm ci --omit=dev

   check what you got

   git status -sb should start ## stable...origin/stable.

   stable is the branch you install from. It moves forward only when a change has been through all three test suites, so it is the newest code anybody is being asked to run. main is where work lands and may be mid-change; do not install from it. npm ci rather than npm install installs exactly what the lockfile says, and --omit=dev skips the test tooling a server does not need.

   A tag would silently break upgrades, which is why this is a branch. git clone --branch <tag> leaves a detached HEAD — on no branch at all. deploy.sh asks git rev-parse --abbrev-ref HEAD what to pull, which on a detached checkout returns the literal string HEAD, so the upgrade pulls the remote's default branch. A box installed from a tag would upgrade itself onto main the first time anybody upgraded it, without saying so. Measured against a real clone, not reasoned about.

   v0.0.2, an old tag, predates logbooks entirely. No operator-built questionnaires, and none of this guide. Do not install it expecting any of this.

6. Run the doctor — now, and after every step

   npm run doctor

   It checks Node, the configuration, the database, the migrations, the media tools, mail and object storage, and for anything missing it prints the install command for your distribution. Right now it will complain about the configuration and the schema, because neither exists yet. That is correct.

   It installs nothing and changes no files. Everything it suggests is printed for you to read first.

   what you should see

   A list of checks, each ok or --, then What is wrong and What to run. At this point it is supposed to complain: there is no configuration and no database schema yet. Those two are the next steps.

   Run it again after every step from here. It is the fastest way to find out whether what you just did took.

7. Configure

   npm run configure

   This writes .env. It asks only for things a person can know — the site's address, the database, the mail and storage credentials — and generates the two encryption keys itself.

   It walks you through, in order: the site origin, the database URL, the port, what the deployment calls itself, the mail transport and its credentials, and object storage. Mail and storage can both be skipped and filled in later.

   as you answer

   The site origin needs the scheme: https://reports.example.org. The port is localhost-only — the app binds 127.0.0.1, so it is not reachable from outside without the proxy.

   Checking an existing .env without changing it

   npm run configure -- --check reports what is missing, including the case that matters most: a half-filled section, which looks configured in the file and behaves exactly as unset. configure itself refuses to overwrite an existing .env.

8. Back up .env — before you go any further

   This is the step people skip and cannot undo. configure just generated two keys: TIER_B_ENCRYPTION_KEY, which encrypts reporters' contact details and wraps the per-file key of every attachment, and CONTACT_HMAC_KEY, which lets a reporter find their own reports.

   They are irreplaceable. Lose either and the data behind it is unreadable forever, with the ciphertext sitting intact in every backup you own. They are never prompted for, never displayed, and exist only in that one file.

   A database backup without .env is a pile of ciphertext nobody can open — including you.

   sudo chmod 600 /srv/reportlog/.env
   sudo chown reportlog:reportlog /srv/reportlog/.env
   sudo cp /srv/reportlog/.env ~/reportlog-env-backup-$(date +%F)

   what you should see

   Nothing. All three are silent when they work, which is normal for Unix and unnerving the first time. Check instead:

   ls -l /srv/reportlog/.env ~/reportlog-env-backup-*

   The first should read -rw------- and reportlog reportlog — owner can read and write it, nobody else can read it at all. The second is your copy, and it is still on the same server, which is not a backup yet.

   Then get that copy off the server and somewhere you trust — a password manager, an encrypted volume, a printed copy in a safe. Treat it like the only copy of a private key, because that is what it is.

9. Build the schema, and set the curtain password

   npm run migrate

   what you should see

   A line per migration — Applying 001_init.sql… and so on, forty-odd of them — ending in Done. Run it a second time and it should print Done. with nothing above it, because they have all been applied.

   Creates every table, index and trigger, and records what has run. Safe to run again — applied migrations are skipped and it says so. If it fails, it is almost always the database URL.

   A fresh install comes up gated with no password set, which means nothing matches it and nobody gets in — including you. That is why this is a step and not an optional extra.

   npm run set-curtain-password

   what you should see

   Two prompts, then a line saying it is set. Nothing appears as you type — no characters, no dots. That is the terminal hiding a password, not a frozen program.

   It asks twice and refuses to finish without one. Minimum eight characters. It never generates one for you: a password nobody chose is a password nobody read carefully, and this one is the only thing in front of the deployment until the rest of it exists. Keep it — you need it at the very last step, and you hand it to whoever will own the deployment.

   The curtain is not authentication and is not a substitute for it. It keeps an unfinished deployment off the open internet; the archive is protected by everything else.

10. Prove mail works

    npm run mail-test -- you@example.org

    you should see

    The mail, in the inbox you named. Wait for it. Do not move on because the command exited without error.

    Prove mail before you hand the site to anybody. Without it the one-time sign-in code is discarded rather than logged — so nobody can sign in, nobody can confirm a report, and the setup wizard cannot be finished, which means the deployment can never be completed at all.

    If it does not arrive

    Check the spam folder first, then your provider's dashboard for a rejection, then npm run doctor, which reports whether the mail configuration is complete enough to try at all.

11. Leave it running

    First check it starts at all:

    npm start

    then, in another terminal

    curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5000/api/health → 200. Ctrl-C to stop it.

    npm start stops when you close the terminal. A service and eight timers keep it going, each timer with a one-shot service of its own, and one command installs and enables all of them:

    sudo ./contrib/install-units.sh --dry-run
    sudo ./contrib/install-units.sh

    reportlog	the app. Required.
    media-worker	processes uploads, every minute. Required if uploads are on — without it an upload sits at “checking” forever.
    anchor	the daily chain timestamp. Required if you want the thing this software is for.
    anchor-watch	checks the anchor above actually ran. Required — a timer being enabled is not the same as the job working, and an anchor that fails every night looks identical to one that does not.
    backup	a verified daily dump. Required — see backups.
    notify-hourly	sends the hourly digest to whoever asked for one. Required once anybody subscribes — they chose it in their own settings, and without this nothing is ever sent.
    notify-weekly	the same digest, with a week's window.
    sweep	deletes expired sign-in codes. Nothing breaks without it; the tables just grow.
    update	applies an update an admin asked for in the Updates pane. Optional — without it the pane still shows what is available and you update over SSH instead.

    Why a script rather than a list of commands

    That script exists because of a real failure. The anchor timer was once missing from a hand-typed list of commands, so a deployment that followed the instructions exactly never anchored — and nothing noticed, because a deployment that is not anchoring looks completely healthy. Every command you type from a list is a chance to stop one short, and the list has grown from five to eight since.

    The script installs whatever ships in contrib/systemd/, so a release that adds a unit is picked up by running it again rather than by anybody noticing.

    check it took

    systemctl list-timers --all | grep reportlog — all eight timers should appear.

12. A certificate, and the proxy

    Certificate first. certbot writes the HTTPS server block and the redirect for you.

    sudo apt install -y certbot python3-certbot-nginx
    sudo certbot --nginx -d reports.example.org

    what you should see

    It asks for an email address (for expiry warnings), makes you agree to the terms, and asks whether to share your address with the EFF — N is fine. Then:

    Successfully received certificate. and the paths it wrote under /etc/letsencrypt/live/. The site is now reachable over https:// and plain http:// redirects to it.

    certbot failed

    “DNS problem: NXDOMAIN” or “no valid A records found”. The hostname does not resolve yet. Go back and check dig +short reports.example.org prints this server's address. Nothing else will work until it does.

    “Timeout during connect”. Port 80 is not reachable. Two usual causes: the firewall (ufw status should list 80 and 443), or your provider's own firewall in their console, which is separate.

    “Unauthorized” and the address it reports is not your server's. Something else is answering for that hostname — most often Cloudflare's proxy. Turn the orange cloud grey and try again.

    Too many failed attempts. Let's Encrypt rate-limits after five failures an hour for the same hostname. Add --dry-run while you work out the problem; it uses a separate, far looser limit.

    Then merge contrib/nginx/reportlog.conf into the block certbot just wrote. Edit its file rather than replacing it — delete and rewrite and the certificate wiring goes with it.

    Five paths must reach the app. nginx serves public/ off disk and everything the app answers has to be proxied: /api/, /docs, /styleguide, /app and /manifest.webmanifest.

    The last one is the dangerous one. It exists both as a file on disk and as a route, so a missing location block does not 404 — nginx serves the file, successfully, with a 200. Nothing looks broken; the deployment just serves a stale copy of something the app was supposed to build, and every home-screen icon is labelled “ReportLog” instead of your deployment's name. It went three days undetected.

    The security policy is one file, included in the server block and again inside location = /sw.js. Do not paste the policy string — including the file means a release that changes the policy reaches your box with git pull.

    include /srv/reportlog/contrib/nginx/csp.conf;

    It appears twice because one add_header anywhere inside a location replaces every header inherited from the server block — that is nginx's rule, not a quirk of this config.

    sudo nginx -t && sudo systemctl reload nginx

    what you should see

    syntax is ok and test is successful, then silence from the reload. The && is load-bearing: it means the reload only happens if the test passed, so a typo in the config cannot take the site down.

    If the test fails it prints the file and line number. Fix that line and run it again — the running nginx is untouched until a test passes.

    Now prove the five paths actually reach the application, which is the thing that silently does not work:

    npm run doctor

    what you should see

    Under Which of these the app answers, all five say the app. If /manifest.webmanifest says nginx instead, the location block for it is missing — that is the 200 described above, and the doctor is the only thing that notices.

    The && matters. A failed test must not reload.

    Two ways an nginx edit goes wrong quietly

    Never leave a backup in sites-enabled/. nginx includes that directory with a bare * and no extension filter, so mysite.bak beside mysite is parsed as a second copy of the same server block. It fails as duplicate listen options, at a line number inside the backup, which reads like a broken config rather than a stray file.

    And it fails late, not now. The running server keeps the config it already parsed, so everything looks fine until something reloads — a certificate renewal, weeks later, with nothing to connect it to your edit. Always finish an edit by testing it.

    cp -a of a sites-enabled entry usually copies a symlink, not a file, so your “backup” points at the very file you are about to change. Use cp -L, or back up the target.

13. Open it, and finish setup

    From here you are in a browser on your own machine, not in the terminal. Visit https://reports.example.org.

    what you should see

    A padlock in the address bar, and a lock screen asking for a password. That is the curtain, and the password is the one you set when you built the schema.

    If you get a browser warning about the certificate, you reached the site over http:// or the hostname does not match the one certbot was given. If you get nginx's default “Welcome” page, the server block certbot wrote is not the one being served — check sudo nginx -T | grep server_name.

    The first-run wizard then runs, once, in six screens:

    1	the owner's email address — this mints the owner, the one account that can appoint or remove an administrator, and a seat that cannot be granted to anybody
    2	a one-time code sent to it — where a broken mail setup stops you dead, which is why the mail test exists
    3	what this archive is called
    4	whether it publishes a public archive
    5	whether people can attach files to a report
    6	the curtain password — keep it, or set a new one

    Screens three to five arrive set to what the software would do anyway and say which answer that is, so you can read them and pass through. Screen six has no default and no skip, deliberately: otherwise a password the installer chose stays live in somebody else's deployment and neither of them notices. Every screen saves before the next is shown.

    Handing it over. If you are installing this for somebody else, what you hand them is the URL and the curtain password. They run the wizard themselves and become the owner. That is the whole point of the split: the installer never has to hold the owner's account.

systemctl is-active reportlog
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5000/api/health
systemctl list-timers --all | grep reportlog
npm run doctor

/api/health sits outside the curtain deliberately, so it answers 200 even while the deployment is locked. It is the cleanest liveness check.

npm run doctor answers most of this now. Besides the configuration, it asks the running deployment three questions nothing in the repository can answer: whether the live nginx config serves a security policy at all, which of the five proxied paths the app actually answered and which nginx answered instead, and whether the timers are enabled and there is a recent backup.

Then, in a browser:

• The lock screen appears, and the password gets you past it.
• Your deployment's name — not “ReportLog” — is in the browser tab.
• You can sign in with a one-time code.
• Build a logbook under Admin, launch it, and file a test report. Click the confirmation link in the email. That path is only reached by a human clicking a link, and it has been broken in production for three days under green test suites for exactly that reason.
• If uploads are on, attach a photo to that test report and confirm it arrives. Nothing in the test suite proves an upload works end to end.

There is a script and a daily timer, and the doctor complains when the newest dump goes stale:

npm run backup                 # take one now
npm run backup -- --check      # report, take nothing

It writes to a temporary name and renames only after reading the dump back with pg_restore --list. A dump interrupted half way is a plausible-looking file of the wrong length, and the one moment nobody checks a backup is while taking it. It prunes only files it wrote, and refuses a BACKUP_DIR inside the checkout.

And check that a restore works. An untested backup is a belief, not a backup.

sudo -u postgres createdb reportlog_restore_test -O reportlog
sudo -u postgres pg_restore -d reportlog_restore_test /var/backups/reportlog/<newest>.dump

This is the part that is not sysadmin work. Take your time over it, because one decision in it cannot be undone.

1 · Create the draft

Sign in, then Admin → Logbooks → Create a logbook. It asks two things.

• What is this logbook called? Reporters see this. A place, a period, a subject — whatever tells somebody they are filing to the right one. “Munich, November 2026” is the shape.
• Web address — optional, and made from the title if you leave it. It is sealed into every report filed here and can never be changed. One chain per logbook, keyed on this. If the one you want is taken, a number is added rather than quietly joining the other logbook’s chain.

Start from one of the shipped question sets rather than an empty form. The dialog offers them, they arrive as a draft you can change freely, and they are a better starting shape than a blank page.

You can also start from a logbook file — the .json a Download as a logbook file gives you, which is how a question set moves between deployments. An upload always arrives as a draft, never as a launched logbook.

2 · Ask your questions

Add a question, one at a time. The types are: short text, long text, date, time of day, date and time, place, choose one, choose any, yes or no, number, email address, web address, evidence they have but are not uploading, and photos, video or documents.

For each one you also decide:

• An answer is needed — the form will not send without it.
• Offer this as a filter on the board. Nothing is filterable unless you say so: there is no built-in date or location filter, because where and when are question types here rather than fixed parts of a report.
• Ask it only when an earlier answer was a particular value, so a follow-up appears for the people it applies to and nobody else.

3 · Read it as a reporter, before you launch

Open the submit page and fill the whole thing in as if you were a reporter. Not a skim — type the answers. It is the only way to notice a question that reads clearly to the person who wrote it and ambiguously to everybody else. Do it on a test box, or remove the test report afterwards.

4 · Launch it, and this is the one-way door

So: read every question aloud, fill the form in once, and only then launch.

When it runs. A logbook can be given an Opens and a Closes time. Launched with an opening time in the future it is scheduled — the state is computed from the clock whenever somebody asks, not flipped by a timer, so it survives the box being down over the boundary.

Closing an intake is not retiring a record. Reports already filed stay published and stay verifiable.

5 · Somebody to review what arrives

Nothing is public until a moderator approves it. There is no auto-publish path and there must not be one. A deployment with a launched logbook and no moderator collects reports nobody can act on.

Access → Roles: an email address, a role, Apply. The person gets a one-time code at that address the first time they sign in — which is the other reason mail had to work before any of this.

The owner’s seat moves only by the two-party handover on the Access screen or by the setup wizard. It appears in no row of the granting table, so there is no code path that produces a second owner.

A moderator may publish a report’s text and withhold its photographs. Never the reverse — consent is the ceiling and moderation is the floor.

6 · File one for real, through the whole path

With the logbook open and a moderator appointed, file a report yourself and follow the confirmation link in the email.

Then you have a working archive, and the address is worth giving out.

Upgrading from the admin page

Admin → Operations → Updates shows what this deployment is running, what is on stable, and the release notes for every version in between. One button installs it: the site takes a database backup, installs, migrates and restarts — about a minute, and a minute of downtime.

It needs reportlog-update.timer, installed with the other units. Without it the pane still tells you an update exists, but the button has nothing listening and npm run doctor says so.

A failed update does not roll itself back. A half-applied migration plus an automatic revert is how an archive gets damaged. The pane shows what failed and the exact rollback command, and a person decides. The backup taken before it started is the way back.

Upgrading over SSH

Every deploy after the first is one command. It refuses to run over uncommitted changes, fast-forwards only, installs from the lockfile, migrates, restarts last, and prints the rollback command if the service does not come back.

cd /srv/reportlog && ./contrib/deploy.sh

Take a dump before any upgrade that runs a migration. Migrations are additive by rule, but a backup you did not need costs nothing. And read the release notes: a release that adds a proxied path needs a one-time nginx edit, because deploy.sh deliberately never edits nginx's configuration.

Starting over on a test box

./contrib/reset-to-fresh.sh

This destroys the archive on that box and puts it back to the state a stranger's install starts in, so the wizard runs again. It never touches .env. Test deployments only. It makes you type the deployment's own SITE_ORIGIN to confirm, after printing the real counts of what it is about to delete — the only confirmation that cannot be given by reflex, and the one that catches the mistake that matters: running it on the wrong box.

When something is wrong

npm run doctor
systemctl status reportlog
journalctl -u reportlog -n 50 --no-pager

Security problems go to security@reportlog.org, never to a public issue.