A Node.js app can work on your laptop and still fail after deployment. The usual causes are simple: the wrong Node version, a hard-coded port, missing environment variables, or a process that runs as root.
When you deploy Node.js app code, production needs more than a working npm start command. You need a repeatable build, a safe secrets process, HTTPS, health checks, logs, and a rollback path. Start by choosing the right hosting model, then prepare the app before sending it to a provider.
Choose where to deploy Node.js app code
Your hosting choice controls how much infrastructure you manage. It also changes the deployment commands, port rules, scaling model, and debugging process.
Managed hosting for the shortest path
Platforms such as Render and Railway connect to a Git repository, install dependencies, run your build command, and start the application. They are a good fit for APIs, internal tools, dashboards, and small production services.
Your repository normally needs:
- A
package.jsonfile with a production start script. - A build script if you use TypeScript or another compile step.
- A server that listens on the provider’s
PORTvariable. - Environment variables configured in the provider dashboard.
Managed platforms usually provide TLS, process restarts, deployment logs, and basic scaling. You still control application security, database permissions, migrations, and monitoring.
VPS hosting for more control
A DigitalOcean Droplet, Hetzner server, or similar VPS gives you a Linux machine. You install Node.js, configure a process manager or systemd, place Nginx in front of the app, and manage updates yourself.
This option gives you more control and often lower infrastructure cost at small scale. It also makes you responsible for firewall rules, operating system patches, backups, certificates, log rotation, and incident recovery.
Choose a VPS when you need custom networking, long-running workers, private services, or full server access. Don’t choose it only because the monthly price looks lower. Your maintenance time is part of the cost.
Containers for repeatable deployments
Docker packages the app with its runtime and dependencies. This makes the deployment easier to reproduce across a laptop, CI system, VPS, Fly.io, AWS, or Google Cloud Run.
Container deployment is useful when you need a predictable build, separate worker processes, or platform portability. It adds Dockerfile and image-management work, but it removes many differences between environments. Docker’s Node.js language guide covers the standard container workflow.
Prepare the application before deployment
A production deployment should not depend on your local machine. Remove local assumptions before you create a server or connect a repository.
Start with a basic package.json structure:
{
"scripts": {
"dev": "node --watch server.js",
"start": "node server.js",
"test": "node --test"
},
"engines": {
"node": ">=24 <25"
}
}
The exact engines range depends on your support policy. The important point is consistency. Test locally with the same major version that production will use.
Your server must listen on the assigned port and all network interfaces:
import http from "node:http";
const port = Number(process.env.PORT || 3000);
const host = "0.0.0.0";
const server = http.createServer((req, res) => {
if (req.url === "/health") {
res.writeHead(200, { "content-type": "application/json" });
res.end(JSON.stringify({ status: "ok" }));
return;
}
res.writeHead(200, { "content-type": "text/plain" });
res.end("Node.js app is running");
});
server.listen(port, host, () => {
console.log(`Listening on ${host}:${port}`);
});
Binding to 127.0.0.1 can work on your laptop but remain unreachable from a container or cloud load balancer. 0.0.0.0 allows traffic from the hosting network.
The /health endpoint should return quickly and avoid expensive database queries. Use a separate readiness check if your platform needs to confirm database or queue availability.
Pin Node.js and install production dependencies
As of September 2026, Node.js 24 is the practical production default. Node.js 22 remains a supported LTS line. Node.js 26 is the current release but has not yet entered LTS. Check the current Node.js release schedule before selecting a version.
Avoid latest image tags and unpinned local runtimes. A future major release can change native modules, language behavior, or dependency compatibility.
Use a version file when your tools support it:
24
Save that file as .nvmrc, or configure the equivalent version setting in your hosting provider. Then verify the version during deployment:
node --version
npm --version
If your repository contains package-lock.json, use npm ci in automated builds. It installs the lockfile’s exact dependency tree and fails when the lockfile and package.json disagree.
For a production-only install, use:
npm ci --omit=dev
The npm ci documentation explains why this command is intended for automated environments. Run tests and builds before removing development dependencies when your build tools are listed in devDependencies.
A common build sequence is:
npm ci
npm test
npm run build
npm prune --omit=dev
npm start
Your provider may combine these steps into separate build and start settings. Render and Railway commonly use the build and start scripts from package.json. Cloud platforms may instead build a container and run its declared command.
Deploy through a managed platform
Managed deployment usually follows this sequence:
- Push the application to GitHub, GitLab, or another supported repository.
- Create a web service.
- Select the repository and production branch.
- Set the build command.
- Set the start command.
- Add environment variables.
- Confirm the application port.
- Deploy and inspect the logs.
For a plain JavaScript application, the settings may be:
Build command: npm ci --omit=dev
Start command: npm start
If the app needs a compile step, use:
Build command: npm ci && npm run build
Start command: npm start
Don’t place secrets in package.json, source files, prompts, or committed .env files. Add values such as these in the provider’s secret configuration:
NODE_ENV=production
DATABASE_URL=...
SESSION_SECRET=...
API_KEY=...
Keep .env files out of Git:
.env
.env.*
!.env.example
Commit an .env.example file with empty or safe sample values. This tells other developers which variables the app requires without exposing credentials.
Railway and Render commonly inject PORT, so your application must read it at runtime. Cloud Run also injects PORT and expects the server to bind to 0.0.0.0. Its container runtime contract documents this requirement.
Deploy a Node.js app with Docker
A small production Dockerfile can use a pinned LTS image:
FROM node:24-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --chown=node:node . .
USER node
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node", "server.js"]
This example assumes the application doesn’t need a compile step. For TypeScript, build in a separate stage and copy only the compiled files and production dependencies into the final image.
Create a .dockerignore file:
node_modules
npm-debug.log
.git
.env
.env.*
coverage
Dockerfile
.dockerignore
Build and test the image locally:
docker build -t my-node-app:local .
docker run --rm -p 3000:3000 --env-file .env my-node-app:local
Then check the health endpoint:
curl http://localhost:3000/health
The node user prevents the process from running as root inside the container. It doesn’t replace application security, but it limits the damage from some container-level mistakes.
Cloud Run, Fly.io, and other container platforms may use different commands to publish and release the image. The Dockerfile stays mostly the same. The provider-specific settings change the image registry, exposed port, region, and scaling rules.
Add graceful shutdown and production safety
A deployment platform may stop or replace your process during a release, scale event, machine restart, or health failure. Your app should stop accepting new work and allow active requests to finish.
function shutdown(signal) {
console.log(`${signal} received, shutting down`);
server.close(async (error) => {
if (error) {
console.error(error);
process.exit(1);
}
// Close database pools, queue consumers, and other resources here.
process.exit(0);
});
setTimeout(() => {
console.error("Forced shutdown after timeout");
process.exit(1);
}, 10000).unref();
}
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));
server.close() stops new connections while existing requests drain. Long-lived WebSocket connections and stuck requests need their own timeout policy. The Node.js process documentation covers process signals and exit behavior. This graceful shutdown example also shows the operational pattern.
Add these controls before production traffic arrives:
- Store secrets in the hosting provider’s secret manager or approved environment configuration.
- Run the service as a non-root user.
- Terminate HTTPS at the managed platform or at Nginx.
- Restrict database access to the application network where possible.
- Set request, upload, and outbound API timeouts.
- Log errors with request IDs, but never log passwords or access tokens.
- Set memory and CPU limits for workers and containers.
- Define what happens when the database or an external API is unavailable.
HTTPS is usually automatic on managed platforms. On a VPS, use Nginx or another reverse proxy with a current certificate. The Node.js process should normally receive trusted internal traffic rather than handling public certificate renewal itself.
Monitor the release and keep a rollback path
A deployment isn’t complete when the provider says “success.” Check the actual service.
Run a smoke test against the public URL:
curl -i https://example.com/health
curl -i https://example.com/api/status
Then test the main user flow in a browser. Check authentication, form submission, database writes, background jobs, file uploads, and error responses.
Monitor at least these signals:
- HTTP 4xx and 5xx rates.
- Request latency.
- Process restarts.
- Memory and CPU use.
- Database connection failures.
- Queue depth and failed jobs.
- External API errors.
- Health check failures.
A healthy deployment can still contain a broken feature. Logs should answer three questions: which request failed, where it failed, and whether it was retried.
Keep the previous image, commit, or release available. A simple rollback method might be:
git checkout previous-known-good
git push origin production
The command differs by provider. Some platforms offer a dashboard rollback. Container platforms may let you point traffic back to an earlier image tag. VPS deployments often use a release directory and a symbolic link.
Don’t run database migrations blindly during every application restart. Use a separate migration command, back up important data, and confirm that the new application remains compatible with the previous database schema during a rollback.
A practical deployment checklist
Before you send traffic to the new release, confirm:
- The production Node.js major version is pinned.
npm cisucceeds with the lockfile.- Tests run in a clean environment.
- The start command works without a developer shell.
- The app reads
PORTfrom the environment. - The server binds to
0.0.0.0. - Required environment variables exist.
- Secrets are not committed or printed in logs.
- Development dependencies aren’t included in the runtime image when unnecessary.
- The process doesn’t run as root.
- HTTPS is active.
/healthreturns the expected status.- Shutdown signals close the server and related resources.
- Logs and error alerts are available.
- The previous release can be restored.
- Database migrations have a recovery plan.
Conclusion
The safest way to deploy Node.js app code is to remove local assumptions before deployment. Pin the Node.js version, install from the lockfile, read the provider port, store secrets outside the repository, and run the process without root access.
Managed hosting is the quickest option for most small services. Docker gives you a repeatable package. A VPS gives you control but adds maintenance. Whichever path you choose, production readiness comes from the controls around the app, not from the hosting brand.
