Node.js (generic) on CloudMagnus

A bare Node site with an allocated upstream port and a placeholder server. Bring your own framework.

What our scaffold installs

  • npm init -y in your htdocs/
  • A placeholder server.js using only Node's built-in http module, listening on 127.0.0.1:<allocatedPort> and responding "Node.js site ready on port <X>"
  • An allocated port from the 3000-3999 pool, unique per site, shown on the site detail page
  • nginx vhost configured to reverse-proxy your domain to 127.0.0.1:<allocatedPort>
  • No database. Generic Node apps don't get one because we don't know which DB you'd want. Contact support for MySQL or Postgres.

What you do next

  1. SSH in (credentials on site detail page).
  2. Replace server.js with your own server, or install a framework: npm install express.
  3. Make sure your server listens on 127.0.0.1:<allocatedPort>, not 0.0.0.0 or a different port. nginx is hardcoded to talk to that exact upstream.
  4. Start your server. Persistent process management is up to you (see below).

Process management

The placeholder server.js exits when your SSH session disconnects, which means your site stops responding. For real use you need a process manager. Options:

  • pm2 (most popular): npm install -g pm2 isn't available globally on our server, but per-site install works: npm install pm2 then ./node_modules/.bin/pm2 start server.js.
  • nohup (simplest): nohup node server.js > logs/app.log 2>&1 &. Survives logout.
  • systemd user units: not currently exposed; contact support if you need a managed unit.

This is a known rough edge. A managed-process UI is on the roadmap.

Node version

The wizard offers Node 18, 20, or 22 LTS. Pick at site creation. Change later from the site detail page.

npm install on deploy

Not automatic. SSH in after uploading new code and run npm install. If you want zero-touch, build your node_modules/ locally and ship it via SFTP (less common; more common to run install on the server).

Common Node issues

502 Bad Gateway

Your Node process isn't listening on the expected port, or it crashed. Check: is the process running? Is it bound to 127.0.0.1:<allocatedPort>? ss -tnlp over SSH shows what's listening.

WebSocket connections drop

nginx is configured to upgrade WebSocket connections by default. If you're seeing drops, it's almost always your application timing out the connection (heartbeat / ping issues) rather than nginx.

"Cannot find module"

npm install didn't run after you uploaded new dependencies. SSH in and run it.

What CloudMagnus doesn't do for Node.js

  • Run npm install automatically. Manual after each deploy.
  • Manage your process. We give you the port; you keep something listening on it.
  • Build your code. Build locally or in CI.