proofpoint-quarantine-portal/deploy

Deploying with systemd

A minimal, single-instance internal deployment. Run once as root on the target VM.

The app is a single process (waitress + an in-process worker thread + SQLite) — see AGENTS.md. Do not run multiple instances or web-server workers.

1. Create the service user and lay down the code

sudo useradd --system --home /opt/ppsq --shell /usr/sbin/nologin ppsq
sudo mkdir -p /opt/ppsq
# copy this repo to /opt/ppsq (git clone, rsync, scp — whatever you use), then:
sudo chown -R ppsq:ppsq /opt/ppsq

2. Install dependencies (as the service user)

cd /opt/ppsq
sudo -u ppsq python3 -m venv venv
sudo -u ppsq venv/bin/pip install --upgrade pip          # avoids "no matching distribution" on old pip
sudo -u ppsq venv/bin/pip install -r requirements.txt     # version ranges; pip picks compatible builds

Requires Python 3.9+. requirements.lock (exact pins from the dev machine) also exists, but only install from it if that exact Python/pip combination matches — otherwise use requirements.txt above.

3. Configure

sudo -u ppsq cp config.example.toml config.toml
sudo -u ppsq chmod 600 config.toml
# generate a session key:
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
sudoedit config.toml   # (or edit as the ppsq user)

Fill in at least: [okta] (issuer/client_id/client_secret/redirect_uri), [pps] host + API credentials, [[auth.users]] (your admins), a real [app] secret_key, and set [app] listen = "127.0.0.1" + cookie_secure = true (you'll front it with TLS). wsgi.py refuses to boot with the placeholder or a <32-char secret_key.

The config.toml and the /opt/ppsq directory must stay writable by ppsq — the admin panel rewrites config.toml, and jobs.db / *.log are written there.

4. Install and start the service

sudo cp /opt/ppsq/deploy/ppsq.service /etc/systemd/system/ppsq.service
# if you used a different path/user, edit the unit first
sudo systemctl daemon-reload
sudo systemctl enable --now ppsq

5. Verify

systemctl status ppsq
journalctl -u ppsq -f          # startup + request logs (also in /opt/ppsq/app.log)
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/login   # -> 200

Reverse proxy (nginx + TLS)

A ready-made site config is in ppsq.nginx.conf — it terminates TLS and proxy_passes to 127.0.0.1:8080. Edit the server_name and ssl_certificate* paths, then:

sudo cp deploy/ppsq.nginx.conf /etc/nginx/sites-available/ppsq
sudo ln -s /etc/nginx/sites-available/ppsq /etc/nginx/sites-enabled/ppsq
sudo nginx -t && sudo systemctl reload nginx

Make sure the Okta redirect_uri matches the public HTTPS URL exactly (e.g. https://ppsq.internal.example.com/authorize), and set [app] cookie_secure = true and listen = "127.0.0.1" in config.toml.

Day-to-day

sudo systemctl restart ppsq        # after editing [app]/[okta] (restart-only keys)
sudo systemctl stop ppsq
journalctl -u ppsq --since '1 hour ago'

Most settings ([pps], [quarantine], users) are editable live in the admin panel and need no restart. See docs/operations.md for logs, backups, and credential rotation, and docs/configuration.md for which keys require a restart.