Docker setup

ForgeSend runs entirely inside Docker Compose: PostgreSQL, Redis, and the backend and frontend themselves are all real Compose services, built from the repository's own Dockerfiles. There's no separate npm install/npm run build step to run yourself, and no process manager like PM2 to configure — Docker Compose is the supported self-hosting path.

Prerequisites

• Docker Engine with the Compose plugin — this guide assumes the docker compose CLI, not the legacy standalone docker-compose binary. Confirm with docker compose version.
• A domain (or at least a stable hostname) you control, if you want anything beyond localhost — CORS_ORIGIN, COOKIE_DOMAIN, and the OAuth redirect vars below all depend on knowing this upfront.
• Optionally, Cloudflare-proxied DNS for that domain — only needed if you want email open/click tracking to work. See Email tracking.
• A valid ForgeSend self-hosted commercial licence — the free Solo tier includes this automatically, so most self-hosters don't need to obtain one separately. See Licensing.

Step 1 — Clone and create your .env

git clone https://github.com/your-org/forgesend.git
cd forgesend

There's no .env.example shipped in the repo — every variable the app reads is documented below, sourced directly from apps/backend/src/config/env.validation.ts. Create a real .env file at the repo root yourself with the values you need, and never commit it.

touch .env

Step 2 — Environment variables

Required — the app will not boot without these

Strongly recommended for anything beyond localhost

Optional — the app boots and runs fine with these unset; each just gates one feature

Frontend-only variables (build-time, not read by the backend at all)

NEXT_PUBLIC_* variables are baked into the client JavaScript bundle at next build time, not read from the environment when the container starts.

Step 3 — Build and start the stack

docker compose up -d --build

This builds and starts all four services defined in docker-compose.yml: postgres, redis, backend (port 4000), and frontend (port 3000).

docker compose logs -f backend

Watch this especially on first boot — the backend container runs prisma migrate deploy automatically every time it starts, before serving traffic, so there's no separate manual migration step for a normal single-instance deployment.

The frontend is reachable at http://localhost:3000, the backend at http://localhost:4000. This setup doesn't include a reverse proxy or TLS termination — put your own in front once you're on a real domain (Caddy, Nginx, or Cloudflare Tunnel all work).

Step 4 — Create your first account

REGISTRATION_ENABLED defaults to false and should stay that way — self-serve public registration is closed by design, not an oversight. The only way to create the first account on a fresh instance is the bootstrap script, run inside the backend container:

docker compose exec backend npx ts-node scripts/bootstrap-admin.ts \
  --email=you@yourdomain.com \
  --password="a genuinely strong password" \
  --name="Your Name" \
  --workspace-name="Your Company"

--name and --workspace-name are optional. On a shared machine, pass the password via the BOOTSTRAP_ADMIN_PASSWORD environment variable instead of a CLI flag, since flags land in shell history:

docker compose exec -e BOOTSTRAP_ADMIN_PASSWORD="a genuinely strong password" backend \
  npx ts-node scripts/bootstrap-admin.ts --email=you@yourdomain.com

Log in normally at /login afterward with the email and password you just created.

Step 5 — Reverse proxy and TLS

Point your domain to the frontend container (port 3000) using Nginx or OpenLiteSpeed. A minimal Nginx config for the frontend:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Set up a similar vhost on a separate subdomain (e.g. api.yourdomain.com) proxying to the backend on port 4000 — this is what NEXT_PUBLIC_API_URL, CORS_ORIGIN, and OAUTH_CALLBACK_BASE_URL should all point at once it's live.

Enable SSL via Let's Encrypt:

certbot --nginx -d yourdomain.com -d api.yourdomain.com

Step 6 — OAuth apps

Google (Gmail inbox connection)

1. Go to Google Cloud Console → APIs & Services → Credentials.
2. Create an OAuth 2.0 Client ID (Web application).
3. Add authorised redirect URI: {OAUTH_CALLBACK_BASE_URL}/inboxes/oauth/google/callback (your backend's URL, not the frontend's).
4. Copy the Client ID and Secret into your .env as GOOGLE_OAUTH_CLIENT_ID / GOOGLE_OAUTH_CLIENT_SECRET.

Microsoft (Outlook inbox connection)

1. Go to Azure Active Directory → App registrations → New registration.
2. Add redirect URI: {OAUTH_CALLBACK_BASE_URL}/inboxes/oauth/microsoft/callback.
3. Under Certificates & secrets, create a new client secret.
4. Copy the Application (client) ID, secret, and tenant ID into your .env as MICROSOFT_OAUTH_CLIENT_ID / MICROSOFT_OAUTH_CLIENT_SECRET / MICROSOFT_OAUTH_TENANT.

Email tracking (opens/clicks)

Setting TRACKING_CNAME_TARGET enables the open/click-tracking subdomain feature, but the tracking subdomain must currently be Cloudflare-proxied (the orange cloud) — the verification flow's error messages explicitly reference Cloudflare's proxy state and SSL/TLS mode.

First-run checklist

1. Run docker compose up -d --build and confirm all four containers are healthy (docker compose ps).
2. Create your admin account with the bootstrap script — see Step 4. There is no web registration form to use instead.
3. Log in at /login and connect an inbox from the Inboxes page.
4. Run a DNS preflight check from the Deliverability page.
5. Send a test campaign to yourself before going live.

Where to go next

Next: Self-hosting overview

• Settings overview
• Deliverability overview
• Inboxes overview