Documentation

Guide / Node.js deployment

Deploy a Node.js app with Railpack

Deploy a Node.js app from GitHub with Railpack. This guide uses the public task board as its example. The sample stores tasks in memory, so a restart restores its three starter tasks. Use the PostgreSQL sample when task data must persist.

Before you start

Create a fork of the sample repository, sign in to Resilis, and connect a GitHub account that can access your fork.

Select the source and target

Start a new application and choose your fork of resilis/nodejs-task-board. Select the main branch. Set the app root to a single dot (.) and choose Development. The verified deployment used Resilis Cloud EU; select an available target in your account.

Configure Railpack

Open Configure and select Advanced build and region settings. The repository has a Dockerfile, so select Railpack for this walkthrough. Leave the install and build commands empty. Set the start command to npm start.

Start command

npm start
Saved Node.js app build settings showing Railpack, blank install and build commands, and npm start.
The captured app uses Railpack with the detected defaults.

Set the app variables

Use Import to add the detected variable names. Import adds names only. Set PORT to 3000 and DEMO_READ_ONLY to false while you test your own editable deployment.

Editable deployment

PORT=3000
DEMO_READ_ONLY=false

Deploy and check the app

Select Deploy Application and wait for the deployment to show Running. Open the live URL and visit /ready. The endpoint reports ready with memory storage. Use the board to add a task and move it between To do, Doing, and Done.

Readiness endpoint

/ready
The live task board shows Deploy my first app in the Doing column.
The task was created and moved during the recorded deployment check.
The restarted task board shows only its three starter tasks.
A restart clears tasks stored in memory.
Transcript: plain-text transcript

Understand restarts and read-only demos

The sample stores tasks in memory. Restarting or redeploying the app clears added tasks and restores the three starter tasks. Use the PostgreSQL sample when task data must persist.

For a shared demo, set DEMO_READ_ONLY to true after your edit checks. Turn off Redeploy current image before saving, then choose Save. Open Configuration, choose Build, and select Rebuild. Verify that GET /api/config reports read-only mode and that a write request returns HTTP 403. The shared demo is already read-only.

How Node.js detection and startup fit together

Railpack prepares the build from the files in the selected app root. For your own Node.js app, commit the dependency manifest and the lockfile for the package manager you use. Check that the production start script exists. If the app needs compilation, confirm that the build produces the files referenced by that script before the runtime process starts.

The sample uses npm start and needs no custom install or build command in this walkthrough. Keep those recorded settings for the example, then review your own application separately. A development server, a script missing from package.json, or a start command pointing at absent compiled output needs correction before deployment.

Match the host, port, and configuration

Make your Node.js web server listen on 0.0.0.0 so that requests can reach it outside the container. Use the configured PORT value in the server listener and align the deployment port with it. This sample sets PORT=3000 explicitly. A port value in a variable is useful only when the running application reads it; do not assume every target assigns it automatically.

For your own app, enter required variable values and mark credentials as secrets. Keep secret values out of source and logs. This memory-backed sample needs no database connection. If your application needs persistent records, follow the PostgreSQL guide and use an internal DATABASE_URL with app and database in the same placement.

Update the source and diagnose failures

With the repository webhook and selected-branch deployment trigger configured, pushing a change to main can start an update for this Development instance. Check the resulting deployment and repeat /ready and board checks. For a manual build, open Configuration, choose Build, and select Rebuild. Confirm the saved source and settings before requesting it.

Use build logs for installation and compilation errors. For a lockfile installation failure, regenerate the lockfile with the package manager used by the app and commit it with the matching manifest. For a missing start script, add the intended script to package.json or correct the start command to an existing production script. Use runtime logs when the image builds but npm start exits or the live app is unavailable. Check required values and the listener before changing unrelated settings. Rollback cannot recover tasks held only in memory.

Node.js deployment questions

Do I need a Dockerfile? Not for this Railpack walkthrough. The repository includes one, but the recorded build explicitly selects Railpack. The Docker guide explains the separate Dockerfile route.

Why does the app refuse edits? The shared demo uses DEMO_READ_ONLY=true and rejects writes with HTTP 403. Use your own fork with false while testing. Check GET /api/config after rebuilding to confirm the applied mode.

Why did my task disappear? Added tasks live in memory in this sample. A restart or redeployment restores the three starter tasks. Use the PostgreSQL version and its rebuild persistence check for stored records.

What should I check after Running appears? Open the live board, call /ready, add a task, and move it between columns. These checks exercise the page and API beyond the deployment status.

Choose the walkthrough that matches your build and storage needs. The examples use different branches or repositories; keep the source and environment from the selected guide together.

Deploy it with your AI agent instead

A connected AI agent can deploy a local workspace through Resilis over MCP, the Model Context Protocol. This route needs Git and an agent with local file and command access; GitHub is unnecessary. Review the source, requested access, target, build settings, and secrets before authorizing the deployment.

Deployment limits and costs

Custom domains are unavailable on connected compute and S3-backed static sites. App rollback does not restore data or reverse database migrations. Review the target capabilities and usage rates before adapting this example.