Installation

How to install ParallelPath on your own Ubuntu server with one interactive script.

Server requirements

What uses what (typical small install, a handful of families):

Optional local AI. If you want an AI model for Tone Check, run it on a separate machine (your desktop GPU, a home server or another VPS) with Ollama or any OpenAI-compatible server, and point ParallelPath at it in the admin portal. A 3-billion-parameter model on CPU needs roughly 4 cores and 4-8 GB RAM - too heavy for a small VPS, which is why the default checker is the lightweight built-in one. You can also use Anthropic Claude via its API.

Before you start

1. A server running Ubuntu 24.04 LTS or newer, which you can SSH into with a sudo-capable account.
2. A domain or subdomain with a DNS A record pointing to the server's public IP. You can install before DNS is ready and get the certificate later.
3. Ports 80 and 443 open to the internet (and UDP 3478 + 49160-49200 for calls). The installer opens them in ufw for you; cloud firewalls (e.g. your VPS provider's panel) you must open yourself.

Run the installer

Copy the ParallelPath folder to the server (or download it from /source) and run:

sudo bash install.sh

The installer is interactive and explains each step. Nothing changes until you've answered every question and confirmed the summary. It's safe to run again - it remembers your answers and keeps existing data and keys.

What it checks first (pre-flight)

• Ubuntu version, CPU architecture, systemd version, TPM2 presence
• Memory and free disk space
• Whether nginx is already installed (and which sites it already serves)
• That ports 80/443 aren't taken by another web server
• Whether PostgreSQL and ufw are already in use
• This server's public addresses and SSH port (so the firewall never locks you out)
• That the clock is synchronised (two-step codes depend on it)

The questions

Then you get a review of everything that will happen.

What it does

1. Installs only the packages needed (Python, PostgreSQL, nginx, and optionally coturn, certbot, fail2ban, cryptsetup).
2. Creates a dedicated parallelpath system user with no shell and no home.
3. Creates the encrypted volume (LUKS2, argon2id) and seals its key with systemd-creds (TPM2 when present). It unlocks automatically at boot. A separate LUKS recovery passphrase is generated for emergencies.
4. Generates the master key, backup key and call-relay secret, sealed with systemd-creds, and builds the encrypted recovery-key bundle /root/parallelpath-recovery.ppexport (PBKDF2-SHA256 + AES-256-GCM with your recovery passphrase). The keys are never written to disk in plain text - only in memory while the bundle is made.
5. Sets up PostgreSQL: a dedicated database inside the encrypted volume, two roles (schema owner and a least-privilege runtime role), socket-only, password-less peer authentication, and triggers that make evidence tables append-only.
6. Installs the application read-only to /opt/parallelpath and builds the public source manifest (with a secret scan).
7. Installs sandboxed systemd services and the AppArmor profile.
8. Adds one nginx site for your domain - testing the configuration first and rolling back automatically if nginx rejects it, so your other sites are never affected.
9. Gets or installs the certificate, and installs a renewal hook.
10. Configures coturn, the firewall, fail2ban and automatic updates.
11. Configures scheduled backups and their destinations, and copies the recovery bundle to them.
12. Creates your first admin account.
13. Runs health checks and prints your links and next steps.

Recovery keys - what to keep and where

Open the bundle any time at https://your-domain/decrypt-export - it runs in your browser and nothing is uploaded. Keep at least one copy of the bundle and your backups away from the server, and the passphrase separate from both.

Everything is logged to /var/log/parallelpath-install.log.

Installing with Docker instead

Prefer containers? See Docker - the same security in hardened Ubuntu 24.04 containers, set up by sudo bash docker/setup.sh.

Installing alongside an existing website

ParallelPath is designed to share a server with other sites:

• It adds a single file, /etc/nginx/sites-available/parallelpath.conf, that only answers for your chosen (sub)domain. nginx.conf and your other sites are not touched.
• The app listens only on 127.0.0.1 (default port 8471, or the next free port).
• It uses its own PostgreSQL database and roles. If PostgreSQL was already installed, its network settings are left as they were.
• Firewall rules are only added.
• If you already have a wildcard certificate (e.g. *.example.com) the installer offers to reuse it for a subdomain. Otherwise it gets a separate Let's Encrypt certificate just for the subdomain using the webroot method - certbot never edits your nginx files.

Example - subdomain of your main site: choose "A subdomain of an existing site", enter example.com and coparent, add a DNS A record for coparent.example.com, and choose Let's Encrypt.

Running ParallelPath under a path (e.g. example.com/coparent) isn't supported - it needs its own (sub)domain for its security cookies and headers.

After installing

1. Copy the recovery bundle off the server (if you didn't set a backup destination), e.g. from your PC: bash scp you@your-server:/root/parallelpath-recovery.ppexport . (Copy it to a readable place first with sudo cp /root/parallelpath-recovery.ppexport /tmp/ && sudo chown $USER /tmp/parallelpath-recovery.ppexport.) Check you can open it at /decrypt-export with your passphrase.
2. Open https://your-domain/admin, sign in and set up two-step verification.
3. In Accounts, invite the first parent.

Getting the certificate later

If you skipped HTTPS or DNS wasn't ready:

sudo ppctl tls

This re-runs only the certificate step: it re-checks DNS, lists certificates already on the server that cover your domain, and lets you choose Let's Encrypt, an existing certificate or your own files.

Upgrading

sudo bash install.sh --upgrade      # from the new version's folder

Upgrades keep all settings, keys and data. The previous code is kept in /opt/parallelpath/src.old. Database schema changes are applied automatically.

Uninstalling

sudo bash /opt/parallelpath/src/install.sh --uninstall

This removes the application, services and nginx site but keeps all data, keys and backups unless you type DELETE EVERYTHING at the final prompt.

Troubleshooting