Node.js

What is Node.js?

Node.js is a JavaScript runtime that lets you run JavaScript on the server. Galaxy supports Node.js 18.x, 20.x, 22.x, and later versions.

Common frameworks you might be running:

• Express: Lightweight and flexible web framework
• Next.js: React framework with built-in API routes
• Fastify: Fast and low overhead web framework
• Koa: Minimalist Node.js framework
• Hapi: Rich framework for building applications

Galaxy handles the runtime for you. Just push your code, and Galaxy spins up your Node.js app.

Prerequisites

Before deploying your Node.js app, ensure you have:

• An active Galaxy account (sign up here if needed)
• Your Node.js app in a GitHub repository
• A package.json file at your repo root (or in a subdirectory)
• A start script defined in your package.json

Getting Started

Head over to the Web Apps Deployment Guide and follow the general deployment steps. Then come back here for Node-specific details about required files and configuration.

Required Files

Make sure your repository includes these essential files:

package.json

This is required. Galaxy reads your package.json to understand your dependencies and how to run your app.

{
  "name": "my-nodejs-app",
  "version": "1.0.0",
  "description": "My awesome Node.js app",
  "engines": {
    "node": ">=20.0.0"
  },
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "build": "optional build step",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

Key fields:

• scripts.start: This is what Galaxy runs to start your app. Make sure it's defined.
• engines.node: Specify which Node.js version you need. Galaxy uses this as a hint.
• dependencies: All production dependencies your app needs to run
• devDependencies: Development-only packages (installed during build, typically not needed at runtime)

server.js or app.js

Your main application file. Galaxy runs your start script, which should point to this file.

const express = require('express');
const app = express();

const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('Hello, Galaxy!');
});

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok' });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Critical: Listen on process.env.PORT, not a hardcoded port. Galaxy passes the PORT environment variable, and your app must use it.

.gitignore

Make sure your git repo excludes files that shouldn't be committed:

node_modules/
.env
.env.local
.DS_Store
npm-debug.log*
yarn-debug.log*
dist/
build/
.next/
out/

Important: Never commit .env files with secrets. Use environment variables in Galaxy instead.

Environment Variables Reference

These are the variables your Node.js app might need. Set them in the Galaxy deployment form.

Core Variables

Common Application Variables

Advanced Configuration

Custom Build Commands

If you need to run build steps (bundling, TypeScript compilation, etc.), define a build script in your package.json:

{
  "scripts": {
    "build": "tsc && webpack",
    "start": "node dist/server.js"
  }
}

Then in Galaxy, set:

• Build Command: npm run build
• Start Command: npm start

Galaxy runs install, then build, then start.

Health Check Endpoint

Create a simple health check endpoint for Galaxy to monitor:

app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'ok',
    timestamp: new Date().toISOString()
  });
});

In the Galaxy deployment form, set Health Check Path to /health. Galaxy checks this endpoint regularly. If it fails, Galaxy knows something's wrong.

Troubleshooting

Build Failures

npm install
npm run build
npm start

Application Won't Start

// Wrong: hardcoded port
app.listen(3000)

// Correct: use PORT env var
app.listen(process.env.PORT || 3000)

Database Connection Issues

Resources

• Express.js Documentation
• Next.js Documentation
• Node.js Best Practices
• Galaxy Community Forum

Need Help?

Having trouble deploying your Node.js app?

• Community Forum
• Galaxy Support
• Knowledge Base