Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/abdelhafid37/talkbox/llms.txt

Use this file to discover all available pages before exploring further.

Deploying TalkBox requires running two separate services: a persistent Node.js process for the Express and Socket.IO server, and a static site host for the compiled React client. Because Socket.IO relies on long-lived WebSocket connections, the server must run on a platform that supports persistent TCP connections — not a serverless runtime. Follow the steps below to go from a local development checkout to a working production deployment.
1

Provision a MongoDB database

Create a MongoDB database that your server can reach over the public internet.
  • MongoDB Atlas (recommended): Create a free-tier cluster at cloud.mongodb.com, create a database user, and whitelist your server’s IP address (or 0.0.0.0/0 during initial setup). Copy the connection string from the Atlas dashboard — it will look like mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<dbname>?retryWrites=true&w=majority.
  • Self-hosted: Ensure your MongoDB instance is reachable from the server host and note the full URI.
Keep the MONGO_URI value ready for the next step.
2

Deploy the server

Upload or clone the server/ directory to your hosting platform (Railway, Render, a VPS, etc.), then set the following environment variables in your host’s dashboard or via a secrets manager — do not ship a .env file in your deployment artefact:
VariableProduction value
PORTPort assigned by your platform, e.g. 8080
MONGO_URIYour Atlas or self-hosted connection string
JWT_SECRETA strong random secret (≥ 32 chars)
CLIENT_URLYour production frontend URL (set after Step 3)
Start the server with npm start, which runs node src/server.js directly. Do not use npm run dev in production — the dev script uses nodemon, which watches the filesystem for changes and restarts the process automatically. That behaviour wastes resources and can cause instability under production load. npm start launches Node without any watcher.
# In your server directory
npm install --omit=dev
npm start
Confirm the server is running by visiting https://<your-server-host>/ — you should see the plain text response TalkBox API Running.
3

Build and deploy the client

In the client/ directory, set VITE_API_URL to the public URL of the server you deployed in Step 2, then run the Vite build:
# In your client directory
VITE_API_URL=https://<your-server-host> npm run build
Vite compiles the React app and writes optimised static assets to client/dist/. Deploy that folder to a static host:
  • Vercel / Netlify: Connect the repository and set the build command to npm run build, the output directory to dist, and the VITE_API_URL environment variable in the project settings.
  • Nginx: Copy the dist/ contents to your web root and add a try_files $uri /index.html; directive so that client-side routing works correctly.
4

Set CORS to match the production frontend URL

The CLIENT_URL environment variable on the server is passed verbatim to both Express CORS middleware and Socket.IO’s CORS configuration. It must match the exact origin of your deployed frontend — including the protocol (https://) and without a trailing slash.For example, if your frontend is served at https://talkbox.example.com, set:
CLIENT_URL=https://talkbox.example.com
A mismatch here will cause all API requests and WebSocket connections from the browser to be blocked by the browser’s same-origin policy. Restart the server after changing this value.
5

Verify the deployment

Open your production frontend URL in a browser and confirm end-to-end functionality:
  1. Register a new user account.
  2. Log in and observe that the user list loads (confirming REST API connectivity).
  3. Open a second browser window or incognito tab, register another user, and send a message between the two accounts.
  4. Confirm that the message appears in real time without a page refresh (confirming WebSocket connectivity).
If messages do not appear in real time, check the browser console for Socket.IO connection errors and verify that CLIENT_URL and VITE_API_URL are consistent with the deployed URLs.

​
Production environment variables reference

The table below summarises every variable required for a production deployment across both services.
ServiceVariableExample production valuePurpose
ServerPORT8080Port the Express server binds to
ServerMONGO_URImongodb+srv://user:pass@cluster.mongodb.net/talkboxMongoDB connection string
ServerJWT_SECRET(strong random string)Signs and verifies JWTs
ServerCLIENT_URLhttps://talkbox.example.comAllowed CORS origin for REST and WebSocket
ClientVITE_API_URLhttps://api.talkbox.example.comBase URL for Axios and Socket.IO client
TalkBox uses Socket.IO for real-time messaging, which requires a persistent WebSocket connection. Serverless platforms (AWS Lambda, Vercel Edge Functions, Cloudflare Workers) do not support long-lived TCP connections and will not work for the server component. Use a platform that runs a continuous Node.js process — Railway, Render (Web Service tier), or a traditional VPS (e.g. DigitalOcean Droplet, Hetzner) are all suitable choices.
On a VPS or any bare Linux server, use PM2 to manage the Node.js process. PM2 keeps the server running after SSH sessions end, restarts it automatically on crash, and provides built-in log management:
npm install -g pm2
pm2 start src/server.js --name talkbox-server
pm2 save          # persist the process list across reboots
pm2 startup       # generate and enable the system startup hook
Use pm2 logs talkbox-server to tail the server output and pm2 restart talkbox-server to apply environment variable changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us