Self-Hosting NuestraVoz Campus on a Production Server

NuestraVoz consists of two Node.js processes — the Astro SSR frontend and the Express API — backed by a Supabase cloud project. Both processes are built from the monorepo’s pnpm build command and can be deployed on any server or managed Node.js platform that supports long-running processes. This guide covers the complete production deployment workflow.

Build

Run the root build command from the monorepo root to compile all packages in the correct order:

pnpm build

This runs pnpm -r build which builds packages/shared first (required by the API), then apps/api and apps/web in parallel. Build outputs:

packages/shared/dist/ — compiled shared types and schemas
apps/api/dist/ — compiled Express server
apps/web/dist/ — Astro standalone server bundle

Environment setup

Before starting either process in production, ensure apps/api/.env contains production values:

apps/api/.env

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_production_service_role_key
PORT=3001
NODE_ENV=production
CORS_ORIGIN=https://campus.nuestravoz.edu
SESSION_COOKIE_NAME=nv_session

Setting NODE_ENV=production enables secure: true on session cookies, which requires HTTPS. Ensure your reverse proxy terminates TLS before traffic reaches the Express process, otherwise browsers will silently discard the session cookie.

Start the processes

Start both processes (API and frontend) with a process manager such as PM2:

# Install PM2 globally (once)
npm install -g pm2

# Start the Express API
pm2 start apps/api/dist/index.js --name nuestravoz-api

# Start the Astro SSR frontend
# Astro node standalone server uses the HOST and PORT env vars
PORT=4321 pm2 start apps/web/dist/server/entry.mjs --name nuestravoz-web

# Save the process list for auto-restart on reboot
pm2 save
pm2 startup

Use pm2 logs nuestravoz-api and pm2 logs nuestravoz-web to tail live logs from each process.

Reverse proxy (Nginx)

Configure Nginx to route all /api traffic to the Express API and everything else to the Astro frontend. The Astro frontend’s Vite dev proxy is only for local development; in production the reverse proxy handles routing.

/etc/nginx/sites-available/nuestravoz

server {
    listen 80;
    server_name campus.nuestravoz.edu;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name campus.nuestravoz.edu;

    ssl_certificate     /etc/letsencrypt/live/campus.nuestravoz.edu/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/campus.nuestravoz.edu/privkey.pem;

    # Route API requests to Express
    location /api {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Route everything else to Astro SSR
    location / {
        proxy_pass http://127.0.0.1:4321;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

After saving the config, test and reload:

nginx -t
systemctl reload nginx

Health check

The API exposes a health check endpoint you can use with any uptime monitor or load balancer:

curl https://campus.nuestravoz.edu/api/health

{ "status": "ok", "service": "nuestravoz-api" }

Property	Development	Production
`httpOnly`	`true`	`true`
`secure`	`false` (HTTP allowed)	`true` (HTTPS only)
`sameSite`	`lax`	`lax`
`maxAge` (remember=true)	30 days	30 days
`maxAge` (remember=false)	1 day	1 day

The secure flag is controlled by config.isDev which is false when NODE_ENV=production.

Run migrations before deploying

Always run database migrations before starting the updated API process:

supabase db push

See the Database setup guide for full migration instructions.

Environment Variables

Full reference for all API environment variables and their defaults.

Database Setup

Supabase project setup, migrations, RLS, and seed data.

Getting Started

Core Features

User Roles

Configuration & Deployment

Build

Environment setup

Start the processes

Reverse proxy (Nginx)

Health check

Run migrations before deploying

Environment Variables

Database Setup

Build docs developers (and LLMs) love

Getting Started

Core Features

User Roles

Configuration & Deployment

Documentation Index

​Build

​Environment setup

​Start the processes

​Reverse proxy (Nginx)

​Health check

​Session cookie behavior in production

​Run migrations before deploying

Environment Variables

Database Setup

Build docs developers (and LLMs) love

Build

Environment setup

Start the processes

Reverse proxy (Nginx)

Health check

Session cookie behavior in production

Run migrations before deploying