Menu

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.

IBM iNode.jsDeploymentOperationsService Commander

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:

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:

  1. curl -i http://127.0.0.1:3000/health returns 200.
  2. curl -i http://127.0.0.1:3000/health/ready returns 200, confirming Db2 access.
  3. An authorized user can list available tools.
  4. A controlled rental and return completes successfully.
  5. Logs contain the request outcome without secrets.
  6. 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:

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.

← Return to Node.js on IBM i

Comments

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