Guide / Node.js and PostgreSQL
Deploy a Node.js app with PostgreSQL
Deploy a Node.js app with PostgreSQL from GitHub. This guide uses the persistent task board as its example. Create the database and app in the same project, environment, and region, then verify that a task survives a new app process.
Before you start
Create a fork of the sample repository, sign in to Resilis, and connect a GitHub account that can access your fork. Keep the database private. Do not use production or unrelated data for this sample.
Create a private PostgreSQL database
In your project, select Create Database. Choose PostgreSQL 17 and name the database taskboard. Select a region and capacity that fit your needs. Keep public network access disabled. The verified example used the Development environment and Resilis Cloud EU.
When the database shows Running, open it and select Connections, then Internal. Select Copy connection URI there. Keep the value private.
Create the app in the same project, environment, and region as the database. This lets the app use the internal database connection. If you select a different environment or region, the internal service name may not resolve.
Select the app source and target
Create an app from your fork of resilis/nodejs-postgres-task-board and select the main branch. Set the app root to a single dot (.). Choose the same project, environment, and region that you used for the database. In the verified example, both resources used the Development environment in Resilis Cloud EU. The sample listens on port 3000, and its Dockerfile exposes that port.
Configure the Dockerfile build
Choose Dockerfile and keep the Dockerfile path set to Dockerfile at the repository root. Leave install, build, and start command overrides empty. The sample Dockerfile exposes port 3000.
Add the database connection as a secret
Paste the connection URI you copied into a DATABASE_URL variable. Turn on the Secret option before you paste it. Keep the URI out of source control, logs, shell history, screenshots, and this guide. Set PORT to 3000 and DEMO_READ_ONLY to false while you test edits. The app must fail to start if PostgreSQL is unavailable; it does not fall back to memory storage.
Other app variables
PORT=3000
DEMO_READ_ONLY=false
Deploy and check readiness
Select Deploy Application and wait for Running. Open the app URL and visit /ready. It should report ready with PostgreSQL storage. If the app is not ready, check that the database is private but available to this app, that DATABASE_URL is a secret containing the internal connection URI, and that PORT is 3000.
Readiness endpoint
/ready Verify persistence across a rebuild
Create a task called Keep this task after restart and move it to Doing. Open Configuration, choose Build, and select Rebuild. This replaces the app process while leaving the database in place. Wait for the deployment to succeed, reopen the app, and confirm that the same task is still in Doing.
Make a shared demo read-only
After the persistence check, set DEMO_READ_ONLY to true. Turn off Redeploy current image before saving, then choose Save. Open Configuration, choose Build, and select Rebuild to apply the saved value. Check GET /api/config for read-only mode. Confirm that POST, PATCH, and DELETE requests return HTTP 403 and leave the task list unchanged. The shared demo is read-only; your own fork stays editable.
Review startup and connection settings
The Dockerfile route packages this Node.js app and starts it with the checked-in image instructions. Review the selected root and branch before rebuilding. For your own service, keep the manifest and lockfile consistent and ensure any compiled output exists in the image. Build logs show installation and image-build failures; runtime logs show what happens after the process starts. For a lockfile installation failure, commit a lockfile that matches the manifest and package manager. For a missing start script, correct the image command or add the intended script to package.json.
Make the web server listen on 0.0.0.0 and the port configured for the deployment. Here PORT=3000 matches the recorded app and Dockerfile. EXPOSE describes the port but does not create a listener. Keep DATABASE_URL as a secret and avoid logging it while diagnosing a connection. For a connection refused error, confirm that the database is Running and DATABASE_URL uses its Internal connection URI, then retry after it is ready. For a hostname resolution error, check that app and database share the project, environment, and region. Keep public access disabled.
Update the app without confusing deployment and data recovery
When the GitHub webhook and selected-branch deployment trigger are configured, pushing a change to main can start an app update. Check the new deployment, /ready, and stored task afterwards. For a manual build, use Configuration, Build, and Rebuild. The existing database remains a separate resource; rebuilding the app is not a database restore.
Before changing a database schema, plan how the previous app version will read the resulting records. App rollback does not reverse migrations or recover deleted data. Keep a separate database recovery plan for destructive changes. Verify that the earlier app can read the current schema before choosing an app rollback. Repeat the stored-task check after an update to confirm that the new process still uses the intended database.
Node.js and PostgreSQL questions
Why does the app fail when the database is unavailable? This sample requires PostgreSQL and does not fall back to memory. Check runtime logs, database status, the secret value, and the same project, environment, and region placement before retrying.
Which connection URI should I use? Copy the Internal connection URI from the running database and store it in DATABASE_URL with the Secret option enabled. Keep the database private for this walkthrough.
How can I check persistence? Create Keep this task after restart, move it to Doing, rebuild the app, and confirm the task remains there. Also confirm that /ready reports PostgreSQL storage so that you are checking the intended app.
Why are writes rejected? The shared demo is read-only and returns HTTP 403 for POST, PATCH, and DELETE. Test edits on your own fork with DEMO_READ_ONLY=false, then apply read-only mode after the persistence check if you want to share a demo.
Related deployment guides
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.