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/pps-quarantine --shell /usr/sbin/nologin pps
sudo mkdir -p /opt/pps-quarantine
# copy this repo to /opt/pps-quarantine (git clone, rsync, scp — whatever you use), then:
sudo chown -R pps:pps /opt/pps-quarantine

2. Install dependencies (as the service user)

cd /opt/pps-quarantine
sudo -u pps python3 -m venv venv
sudo -u pps venv/bin/pip install --upgrade pip          # avoids "no matching distribution" on old pip
sudo -u pps 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 pps cp config.example.toml config.toml
sudo -u pps chmod 600 config.toml
# generate a session key:
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
sudoedit config.toml   # (or edit as the pps 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/pps-quarantine directory must stay writable by pps — the admin panel rewrites config.toml, and jobs.db / *.log are written there.

4. Install and start the service

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

5. Verify

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

Reverse proxy (TLS)

Terminate TLS at nginx/Caddy and proxy to 127.0.0.1:8080. Make sure the Okta redirect_uri matches the public HTTPS URL exactly (e.g. https://pps.internal.example.com/authorize). Minimal nginx:

server {
    listen 443 ssl;
    server_name pps.internal.example.com;
    ssl_certificate     /etc/ssl/pps.crt;
    ssl_certificate_key /etc/ssl/pps.key;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Day-to-day

sudo systemctl restart pps        # after editing [app]/[okta] (restart-only keys)
sudo systemctl stop pps
journalctl -u pps --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.