Lesson 19 · Node.js on IBM i — From RPG Developer to Modern IBM i Developer
Deploy and Operate Node.js on IBM i
Promote a tested release, install exact dependencies, run it as a managed IBM i service, verify health, and prepare a rollback.
Deployment is not copying a few JavaScript files and starting a background shell. A supportable release includes the exact source, dependency lock file, SQL changes, configuration definition, service identity, verification steps, and a rollback plan.
The commands below are a model. Adapt paths, profiles, change control, networking, and service management to your organization.
Build a release from a known commit
Tag the commit that passed review and tests:
git status
npm test
git tag tool-rental-v1.0.0
Promote that commit through your normal repository or CI/CD process. Do not deploy whichever files happen to be in a developer’s home directory.
The production release must retain:
- The complete application source
package.jsonandpackage-lock.json- SQL migration scripts and their applied status
.env.exampleand operating documentation- The Git commit or release identifier
Keeping the source that matches production is especially important for Node.js because the deployed JavaScript is the application, not merely an intermediate build input.
Install in a controlled IFS location
Use a deliberately owned release directory, for example:
/apps/tool-rental/releases/1.0.0
/apps/tool-rental/current
/apps/tool-rental/shared
The current path can point to the active release. Configuration and logs can live under shared with tighter permissions and remain separate from versioned source.
Place the tagged source in a new release directory. One way is to clone the tag straight from your Git server; the URL below is a placeholder:
mkdir -p /apps/tool-rental/releases /apps/tool-rental/shared
git clone --branch tool-rental-v1.0.0 --depth 1 \
ssh://git.example.com/tool-rental.git /apps/tool-rental/releases/1.0.0
cd /apps/tool-rental/releases/1.0.0
npm ci --omit=dev
Create the production settings once, outside the release, and make them readable only by the service profile and its administrators:
cp .env.example /apps/tool-rental/shared/tool-rental.env
chmod 640 /apps/tool-rental/shared/tool-rental.env
Edit that file and set APP_ENV=production. Then point current at the new release:
ln -sfn /apps/tool-rental/releases/1.0.0 /apps/tool-rental/current
current is a symbolic link. Changing where it points is how a release is activated, and later how one is rolled back.
In those commands, npm ci uses the committed lock file and refuses an inconsistent dependency definition. Install on IBM i because idb-pconnector contains platform-specific components and installs only there.
Apply database changes deliberately
Record which SQL scripts have been applied in each environment. Back up affected data when required and test forward and rollback procedures before the production window.
For this first release, apply the schema, seed only approved production reference data, and create the procedures. Do not run the development seed script in production.
Manage the service
IBM i teams may already have an approved job or service manager. Use it.
Service Commander is one IBM i option for managing open-source applications. Install it with yum install service-commander. Each service is described by a small YAML file. Create tool-rental.yaml in the Service Commander services directory, which is /QOpenSys/etc/sc/services for system-wide definitions:
name: Tools Rental
dir: /apps/tool-rental/current
start_cmd: /QOpenSys/pkgs/lib/nodejs24/bin/node --env-file=/apps/tool-rental/shared/tool-rental.env src/server.js
check_alive: '3000'
batch_mode: 'true'
sbmjob_jobname: TOOLRENT
sbmjob_opts: USER(TOOLAPP)
Read it as a description of the job:
dir Directory the service starts in
start_cmd Command that starts it, with the full path to node
check_alive Port that shows the service is running
batch_mode Submit it as a batch job
sbmjob_jobname Job name operators will see in WRKACTJOB
sbmjob_opts Extra SBMJOB parameters, here the service profile
Operators then have one consistent set of commands:
sc start tool-rental
sc check tool-rental
sc stop tool-rental
Treat this as a starting example and confirm the current Service Commander fields and organizational standards before use. Avoid relying on nohup as the production operating model; it does not give operators a complete start, stop, status, logging, and restart process.
Verify the release
After starting the service, verify more than the process:
curl -i http://127.0.0.1:3000/healthreturns 200.curl -i http://127.0.0.1:3000/health/readyreturns 200, confirming Db2 access.- An authorized user can list available tools.
- A controlled rental and return completes successfully.
- Logs contain the request outcome without secrets.
- The running Node.js version and application release match the deployment record.
Monitor job CPU, memory, open database connections, response time, error rate, log growth, and disk usage. Agree on who receives alerts and what they should do.
Prepare rollback before deployment
Keep the previous release directory intact. A rollback may involve:
- Stop the current service
- Restore database state or apply a tested backward migration when required
- Point
currentto the previous release - Start the previous version
- Repeat health and business checks
When the database has not changed between the two releases, the application part is three commands and the health checks:
sc stop tool-rental
ln -sfn /apps/tool-rental/releases/0.9.0 /apps/tool-rental/current
sc start tool-rental
curl -i http://127.0.0.1:3000/health/ready
Practise this in a test environment before the first production deployment. A rollback that has never been run is only a plan.
Database changes determine whether application rollback is safe. An application version cannot be rolled back blindly when it no longer understands the database schema.
The final lesson reviews the finished system and gives the learner a practical definition of done.
References
Documentation and references used for this lesson.

Comments
Share your thoughts, questions, or real-world IBM i experiences related to this article.