Deploy Sealearn: Backend on Node.js and Frontend on Vercel

Sealearn is a split-stack application: the Express API (backend) and the React + Vite client (frontend) are deployed independently. The backend can run on any Node.js 18+ host — Railway, Render, Fly.io, a bare VPS, or a Docker container — while the frontend is optimised for Vercel and ships with a vercel.json rewrite rule that ensures React Router works correctly for all client-side routes. This guide walks through both deployments in order, then covers OAuth callback registration, production environment variables, and database seeding.

Backend
Frontend (Vercel)

Backend Deployment

Requirements

Requirement	Minimum version / notes
Node.js	18 LTS or later
MongoDB	Atlas M0 free tier or self-hosted 6.x+
Redis	Upstash free tier, Redis Cloud, or self-hosted 6.x+

Provision external services

Before deploying the API itself, make sure the three stateful services are ready:

MongoDB — Create a MongoDB Atlas cluster and copy the SRV connection string. Whitelist your backend host IP in the Atlas Network Access panel (or use 0.0.0.0/0 for managed platforms that do not expose a stable egress IP).

Redis — Create an Upstash Redis database and copy the rediss:// URL from the connection details page. Upstash’s free tier is sufficient for development and low-traffic production workloads.

Cloudinary — Create a free account and note your cloud name, API key, and API secret from the dashboard.

Set environment variables

Set every variable listed in the Environment Variables reference on your hosting platform. The minimum set required for the backend to start and serve all routes in production is:

PORT=8080
MONGODB_URI=mongodb+srv://...
REDIS_URL=rediss://...
JWT_SECRET=<long-random-string>
CLIENT_URL=https://your-app.vercel.app
CLIENT_URL_WWW=https://www.your-app.vercel.app
FRONTEND_URL=https://your-app.vercel.app
BACKEND_API=https://your-api.domain
GROQ_API_KEY_1=gsk_...
GEMINI_API_KEY=AIzaSy...
RESEND_API_KEY=re_...
RESEND_FROM=SEA <noreply@yourdomain.com>
CLOUDINARY_CLOUD_NAME=...
CLOUDINARY_API_KEY=...
CLOUDINARY_API_SECRET=...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_CALLBACK_URL=https://your-api.domain/api/auth/google/callback
DISCORD_CLIENT_ID=...
DISCORD_CLIENT_SECRET=...
DISCORD_CALLBACK_URL=https://your-api.domain/api/auth/discord/callback

Deploy and start the server

The production start command is:

node server.js

For local development with automatic restarts on file changes, use the dev script which runs nodemon:

npm run dev

On platforms like Railway or Render, point the start command to node server.js. The server will connect to MongoDB first and only begin accepting HTTP traffic after the database connection succeeds.

Verify the health check

Once the server is running, confirm it is accepting requests by calling the health endpoint. A successful response looks like this:

curl https://your-api.domain/api/health

{
  "ok": true,
  "message": "SEA API corriendo",
  "timestamp": "2025-01-15T12:00:00.000Z"
}

Use this endpoint as your platform’s health-check probe. On Railway, Render, and Fly.io you can configure it under the service health-check settings so the platform automatically restarts unhealthy instances.

Seed the database

Run the subject and shop seed scripts once after the first deploy (or after wiping the database). These scripts connect to MONGODB_URI and insert the default curriculum data that the frontend expects:

node seeds/seedSubject.js
node seeds/seedShop.js

Do not run the seed scripts against a production database that already has live user data — they are designed for initial setup and may overwrite existing records.

Configure CORS

Set CLIENT_URL and CLIENT_URL_WWW to your Vercel deployment domain. The CORS middleware in server.js builds its allow-list from these two values plus a dynamic regex that also permits any preview deployment URL matching https://sea-frontend*.vercel.app:

// server.js (excerpt — do not edit, shown for reference)
app.use(cors({
  origin: [
    process.env.CLIENT_URL || "http://localhost:5173",
    process.env.CLIENT_URL_WWW || "http://localhost:5173",
    /https:\/\/sea-frontend.*\.vercel\.app$/
  ],
  credentials: true,
}));

If your Vercel project slug does not start with sea-frontend, add your exact domain to CLIENT_URL and requests will still be allowed.

Frontend Deployment on Vercel

The React frontend is built with Vite and is designed to be deployed on Vercel with zero additional configuration beyond setting one environment variable.

Connect the repository to Vercel

Go to vercel.com/new and import your repository.

Set the Root Directory to frontend/sea (the directory that contains package.json and vite.config.js).

Vercel will auto-detect the Vite framework. Confirm the following build settings:

SettingValueBuild commandnpm run buildOutput directorydistInstall commandnpm install

Set the backend URL environment variables

In the Vercel project settings under Environment Variables, add both of the following:

VITE_API_URL=https://your-api.domain
VITE_SOCKET_URL=https://your-api.domain

VITE_API_URL is used by the Axios client to prefix all REST API requests. VITE_SOCKET_URL is used by the Socket.IO clients for real-time features — the duel system, the chat namespace, and friend-invite state all connect to this URL. Both variables are inlined into the frontend bundle at build time by Vite.

Vite only exposes environment variables prefixed with VITE_ to the client bundle. Any variable without that prefix is ignored at build time and will be undefined in the browser.

Understand the vercel.json rewrite rule

The frontend/sea/vercel.json file contains a single rewrite rule:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

This rule tells Vercel’s CDN to serve index.html for every request path that does not match a static asset file. Without it, a user who navigates directly to a URL like https://your-app.vercel.app/dashboard would receive a 404 from Vercel instead of landing in the React app and letting React Router handle the route.

Deploy

Click Deploy. Vercel will run npm run build, output the bundle to dist/, and publish it to its global CDN. Subsequent pushes to the production branch trigger automatic redeployments.

Vercel also creates a unique preview URL for every pull request. These preview URLs match the https://sea-frontend*.vercel.app regex already in the backend CORS config, so API requests from PR previews work without any extra configuration as long as your Vercel project slug starts with sea-frontend.

OAuth Callback URLs

After deploying the backend, register the following callback URLs in each OAuth provider’s developer console. The paths are fixed and must match exactly.

Google

Open the Google Cloud Console → APIs & Services → Credentials.
Edit your OAuth 2.0 client and add the following to Authorised redirect URIs:

https://your-api.domain/api/auth/google/callback

Set GOOGLE_CALLBACK_URL on the backend to the same value.

Discord

Open the Discord Developer Portal → your application → OAuth2.
Add the following to Redirects:

https://your-api.domain/api/auth/discord/callback

Set DISCORD_CALLBACK_URL on the backend to the same value.

OAuth providers reject redirects to URLs that are not explicitly registered. If you change your API domain, update the callback URLs in both the provider console and the corresponding backend environment variables simultaneously, otherwise all OAuth logins will fail with a redirect-mismatch error.

Production Checklist

Use this checklist before going live:

[ ] MONGODB_URI points to a production Atlas cluster (not a dev/test cluster)
[ ] REDIS_URL is set and the connection is verified
[ ] JWT_SECRET is at least 32 random characters and not shared with any other environment
[ ] CLIENT_URL and CLIENT_URL_WWW are set to the production Vercel domain
[ ] GOOGLE_CALLBACK_URL and DISCORD_CALLBACK_URL match the registered redirect URIs
[ ] RESEND_FROM uses a domain verified in the Resend dashboard
[ ] At least one of GROQ_API_KEY_1/2/3 or GEMINI_API_KEY is set
[ ] Seed scripts have been run once: node seeds/seedSubject.js && node seeds/seedShop.js
[ ] VITE_API_URL and VITE_SOCKET_URL are set in the Vercel project environment variables
[ ] GET /api/health returns { ok: true } from the production URL

Get Started

Core Features

Configuration

Deploy Sealearn: Backend on Node.js and Frontend on Vercel

Backend Deployment

Requirements

Frontend Deployment on Vercel

OAuth Callback URLs

Google

Discord

Production Checklist

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Documentation Index

​Backend Deployment

​Requirements

​Frontend Deployment on Vercel

​OAuth Callback URLs

​Google

​Discord

​Production Checklist

Build docs developers (and LLMs) love

Backend Deployment

Requirements

Frontend Deployment on Vercel

OAuth Callback URLs

Google

Discord

Production Checklist