Skip to main content
This guide covers deploying Mocha on an Ubuntu 22.04+ (or Debian 12+) VPS without Docker.

Prerequisites

  • A server running Ubuntu 22.04+ or Debian 12+
  • A domain or subdomain pointed at your server’s IP
  • SSH access as a non-root user with sudo

1. Install dependencies

Bun

Verify:

Node.js & PM2

PM2 is used to keep Mocha running as a background service and restart it on crash or reboot.

PostgreSQL

Create a database and user:

Nginx

2. Clone and install

3. Configure environment variables

API (apps/api/.env)

Use openssl rand -hex 32 to generate a strong secret.

Client (apps/client/.env)

4. Database setup

5. Build

6. Start with PM2

From the repo root:
Run the command printed by pm2 startup to configure PM2 to start on boot. Verify everything is running:
You should see both client and api listed as online.

7. Configure Nginx

Client proxy

API proxy

Test and reload Nginx:

8. Enable SSL

Certbot will automatically configure HTTPS and schedule auto-renewal.
After enabling SSL, make sure NEXT_PUBLIC_API_URL in apps/client/.env uses https://. Rebuild (bun run build) and restart PM2 (pm2 restart all) for the change to take effect.

Default credentials

Change the default password immediately from Settings → Profile after first login.

Updating Mocha