Deployment

This page covers building each package for production, the environment variables required, hosting options, and common deployment pitfalls.

Production build commands

Run these from the repo root. Each command triggers next build inside the respective package.

# Build backend API
pnpm --filter @repo/backend-js build
 
# Build frontend app
pnpm --filter @repo/frontend-app build
 
# Build documentation site
pnpm --filter @repo/docs build

After building, start each service with its start script (Next.js production server):

pnpm --filter @repo/backend-js start   # runs on the port next start listens to
pnpm --filter @repo/frontend-app start
pnpm --filter @repo/docs start

[!TIP] In a process manager like PM2, map each package to a start command and assign ports via PORT environment variable (e.g. PORT=3001 pnpm --filter @repo/backend-js start).

Port assignments

Use a reverse proxy (nginx, Caddy, Traefik) in front of all three services to terminate TLS and route by hostname or path prefix.

Required environment variables in production

backend-js

All of these must be set via your deployment platform’s secrets manager (never committed to the repo).

[!WARNING] JWT_SECRET and DEFAULT_USER_PASSWORD have hardcoded fallbacks in src/app/config/envConfig.ts. These fallbacks are visible in the public repository. If you deploy without overriding them, any attacker can forge JWT tokens and know the initial password of every created user.

frontend-app

MySQL in production

Connection pooling

The backend uses mysql2 with a connection pool (src/app/config/dbConfig.ts). The pool is a module-level singleton — it is created once when the module first loads and reused across all requests.

Key considerations:

• Set connectionLimit to match your MySQL server’s max_connections capacity. A typical starting value is 10.
• In serverless environments (Vercel, AWS Lambda), each function invocation may spawn a new pool. This can exhaust MySQL connections quickly. Consider using PlanetScale or Neon with their HTTP drivers, or a dedicated connection proxy like ProxySQL or RDS Proxy.
• In self-hosted deployments (a single long-running Node process), the pool behaves correctly as-is.

SSL / TLS

If your production MySQL instance requires TLS (common on managed services like AWS RDS, GCP Cloud SQL, Azure Database for MySQL), add SSL configuration to the pool options in dbConfig.ts:

ssl: {
  rejectUnauthorized: true,
  ca: process.env.MYSQL_SSL_CA,
}

And add MYSQL_SSL_CA (PEM content) to your secrets.

Next.js hosting options

Option A — Vercel (recommended for frontend-app)

The frontend is a standard Next.js App Router application and deploys to Vercel with zero configuration.

1. Connect the repository in the Vercel dashboard.
2. Set Root Directory to frontend-app.
3. Add all NEXT_PUBLIC_* environment variables in the Vercel project settings.
4. Deploy.

[!NOTE] Vercel does not run the backend. Deploy backend-js separately on a VPS or container platform so it has a persistent MySQL connection.

Option B — Self-hosted (VPS / Docker)

Run each service as a long-lived process behind nginx:

# nginx snippet — route by subdomain
server {
    server_name api.tolosaerronka.es;
    location / { proxy_pass http://localhost:3001; }
}
server {
    server_name tolosaerronka.es;
    location / { proxy_pass http://localhost:3000; }
}
server {
    server_name docs.tolosaerronka.es;
    location / { proxy_pass http://localhost:3002; }
}

Use Certbot to provision TLS certificates automatically.

Cookie and CORS configuration

The authentication flow uses an HttpOnly refresh_token cookie issued by the backend and sent automatically by the browser on every /api/auth/refresh call.

For this to work cross-origin in production:

If the frontend and backend are on different subdomains, the browser will only send the None; Secure cookie if TLS is active end-to-end. An HTTP-only deployment will silently drop the refresh cookie after login.

[!WARNING] Never set Access-Control-Allow-Origin: * when credentials: true is required. The browser will reject such responses. Always specify the exact frontend origin.

Health check endpoints

There is no dedicated /health endpoint in the current codebase. The simplest proxy health check is:

GET /api/auth/me

This endpoint always responds with a JSON body (either 401 Unauthorized or the authenticated user). A non-5xx response confirms the backend is up and MySQL is reachable.

Common deployment pitfalls