Install Proofroom

Proofroom runs on your own server, one stack per company, installed and looked after by proofroomctl. Installing takes about 10 minutes. A free trial gives you a licence for 14 days and up to 25 users: start one on proofroom.com.

Rather not install it yourself? An AI agent can do it with the agent guide, or a partner or IT provider can install it for you: write to hello@proofroom.com and we will put you in touch.

Before you start

You need:

• A server running Ubuntu 24.04 or Debian 12 on x86-64, with at least 2 GB of memory (8 GB recommended) and 20 GB of free disk, reachable from the internet on ports 80 and 443 (for the HTTPS certificate), and an account on it that can use sudo (root also works).
• A DNS record for the domain Proofroom will run on (for example proofroom.acme.com) pointing at the server’s public IP address. Set it first: the certificate is issued when Proofroom is created, and DNS can take a while to reach everyone. Check it with dig +short proofroom.acme.com; it should print the server’s address.
• Nothing else running on ports 80 and 443 on that server.
• Your install code (in the trial email and on the download page) or your licence file, <your domain>.proofroom-licence.json. For a trial on a domain outside your email’s (proofroom.acme.io for jo@acme.com), the trial page first asks for a TXT record on that domain to show it is yours.

Install with one command

Sign in to the server and run, with your code:

curl -fsSL https://proofroom.com/install.sh | sudo bash -s -- --code XXXX-XXXX-XXXX

The commands on this page use sudo. Signed in as root on a server without sudo (Debian)? Leave out sudo, here and below.

Read the script first. Download this release’s script and its SHA-256, read it, check it, then run it:

curl -fsSLO https://proofroom.com/install-1.14.4.sh
curl -fsSLO https://proofroom.com/install-1.14.4.sh.sha256
less install-1.14.4.sh
sha256sum -c install-1.14.4.sh.sha256
sudo bash install-1.14.4.sh --code XXXX-XXXX-XXXX

sha256sum -c prints install-1.14.4.sh: OK when the file is the one published. The .sha256 file catches a broken or partial download, not a compromised site: it comes from the same site as the script. To check against a second source, compare the hash with the one each release’s notes print (release notes). A versioned script such as install-1.14.4.sh and its .sha256 never change, so a hash you noted stays valid after later releases; install.sh is always the newest, with its own hash at proofroom.com/install.sh.sha256. The script sends your install code to the licence server and nothing else, and never asks for a password or a key.

What it does. It checks the server first, printing ✓ or ✗ for each check, and stops at the first problem with what to do: sudo or root, the system (Ubuntu 24.04 or Debian 12), x86-64, memory, disk, ports 80 and 443, that the licence server and the image registry can be reached, and that your domain points at this server. Then it fetches your licence with the code and saves it in /root/proofroom-licence.json (so running it again needs no code), installs Docker if it is missing and then proofroomctl, prepares the server (proofroomctl init), creates your Proofroom (proofroomctl create) and prints a one-time setup link. Open it, choose your password and add Proofroom to your authenticator app (Google Authenticator, 1Password, Microsoft Authenticator or similar): you are signed in as the first admin. The link works once and for 24 hours; for a new one, sudo proofroomctl admin-link <stack name> --email <your email>. Before installing anything it asks you to confirm ([y/N]); add --yes to skip the question, which you need when there is no terminal to answer it (cloud-init, or ssh host 'curl … | sudo bash …'). Running the command again is safe: if a stack with that name already exists, it says so, shows its status and how to get a new link or start over, and exits with status 1 if the stack is not healthy.

A code that was used or is more than 7 days old gets “This install code is not valid”: write to hello@proofroom.com for a new one, or install by hand with your licence file.

Prefer to do it by hand?

1. Copy the licence file to the server, from the computer you saved it on:

   scp <your domain>.proofroom-licence.json <you>@<your server>:~/
   

2. Sign in to the server and install Docker:

   ssh <you>@<your server>
   curl -fsSL https://get.docker.com | sudo sh
   

3. Install proofroomctl, the tool that installs and looks after Proofroom:

   sudo docker run --rm --entrypoint cat ghcr.io/proofroom-team/proofroom:1.14 \
     /app/release/proofroomctl | sudo tee /usr/local/sbin/proofroomctl > /dev/null
   sudo chmod 755 /usr/local/sbin/proofroomctl
   sudo proofroomctl init
   

   init checks the server and sets up Caddy, the web server that gets the HTTPS certificate.

4. Create your Proofroom. The stack name is yours to choose (2 to 31 lower-case letters, digits or dashes, starting with a letter):

   sudo proofroomctl create <stack name> --domain <your domain> \
     --licence ~/<your domain>.proofroom-licence.json --admin-email <your email>
   

   It takes a few minutes and ends by printing a one-time setup link.

5. Open that link in your browser, choose your password and add Proofroom to your authenticator app. You are signed in as the first admin. The link works once and for 24 hours. For a new one:

   sudo proofroomctl admin-link <stack name> --email <your email>
   

First steps in Proofroom

• Admin → Settings → Email: set up your mail provider, so invitations and password resets are emailed.
• Admin → Users: invite your team. Until email is set up, Proofroom shows each invitation link for you to pass on.
• Admin → Frameworks: the frameworks you are assessed against, with every control and its evidence.
• Integrations: connect your cloud, identity and code systems so evidence is collected for you.

Looking after it

sudo proofroomctl status <stack name>    # health, version, licence and last backup
sudo proofroomctl backup <stack name>    # a backup now (one is also taken every night)
sudo proofroomctl update <stack name>    # the latest release; it backs up first and rolls back if anything fails

sudo proofroomctl help lists every command, and sudo proofroomctl help <command> (or man proofroomctl) describes one: its options and defaults, exit codes and examples. The same reference is online: Command reference. Put -s before a command to see what it would change, without changing anything: sudo proofroomctl -s update <name>.

Before update, copy the newest backup and /srv/proofroom/stacks/<stack name>/app.env off the server (for example with scp or rsync). app.env holds the key that decrypts your evidence; keep it separate from the backup and safe.

To keep backups off the server every night, open Admin → Backups and add an S3-compatible bucket you own; each nightly backup is then uploaded there, and Proofroom never receives it. app.env (with MASTER_KEY) is not uploaded, so keep a copy of it somewhere safe off the server as well. Until a bucket is set up, the dashboard reminds admins that the backups are only on this server.

From 1.5.0 an admin can also update from Proofroom: Admin → Updates shows when a newer release is out, and Update now runs the same update, with the same backup first and rollback. The dashboard tells admins when there is one. Copy the backup off the server afterwards in the same way. How it works, and how to turn the daily check off: Running Proofroom, section 6.

Admin → About has this version’s SBOM (the list of everything in it, CycloneDX JSON) for your security team, and the result of the scan it passed before release.

Settings

Single sign-on is set in /srv/proofroom/stacks/<stack name>/app.env. Email is set in Proofroom itself, or in the same file if you automate your installs. Edit it with sudo (sudo nano …/app.env), then run sudo proofroomctl restart <stack name>.

Single sign-on (Microsoft Entra ID, Okta, Google or any OIDC provider). Register Proofroom with your provider using the redirect URI https://<your domain>/api/auth/callback/oidc, then set:

Email (invitations, reminders and password resets). Proofroom sends through your own mail provider, never ours.

In Admin → Settings → Email, choose how to send (SMTP, SendGrid or SMTP2GO), enter the from address and your provider’s details, and save. Passwords and API keys are encrypted and never shown again; Replace changes one. Then send a test email: it goes through the saved settings, and a failure is explained in plain words.

To set email in app.env instead (for example, when you automate installs), use the settings below. When MAIL_TRANSPORT is set there to anything but none, it wins: the page shows it read-only, and you remove the MAIL_* lines to manage email in Proofroom again.

AI features (optional: control suggestions, vendor facts, Workflow check suggestions and the evidence check) use your own TypeSafe account. Enter its API key in Admin → Settings → AI model → API key: it is encrypted and never shown again (Replace and Remove change it). TYPESAFE_API_KEY in app.env still works and wins when set; the page then shows “Set in app.env” and the field is off. Without a key everything else works.

Buying, and help

Write to hello@proofroom.com. Buying converts your trial licence in place, so everything you set up stays as it is. If something in these steps does not work, send us what you ran and what it printed.