usabilitydynamics/udx-worker-nodejs repository overview

⁠UDX Worker Node.js

Secure, containerized Node.js runtime built on UDX Worker for repeatable service execution and automation.

⁠Quick Reference

• Where to get help: https://udx.dev/worker⁠
• Source: https://github.com/udx/worker-nodejs⁠
• Dockerfile: https://github.com/udx/worker-nodejs/blob/latest/Dockerfile⁠
• Base image: https://hub.docker.com/r/usabilitydynamics/udx-worker⁠

⁠Supported Tags

• latest
• Semantic version tags (recommended for CI/CD pinning)

⁠What It Is

UDX Worker Node.js extends usabilitydynamics/udx-worker with a verified Node.js runtime. It keeps the same runtime model as the base image, including non-root defaults, service supervision, and structured runtime configuration.

⁠Highlights

• Runs as a non-root udx user by default.
• Includes Node.js runtime with checksum verification during image build.
• Uses the same worker.yaml and services.yaml model as udx-worker.
• Inherits worker CLI support for service control and auth verification.
• Consistent behavior across local machines, CI/CD, and Kubernetes.

⁠Quick Start

⁠1) Create Project Files

mkdir -p my-node-worker/src my-node-worker/.config/worker
cd my-node-worker

cat > src/server.js <<'JS'
const http = require('http');
const port = process.env.PORT || 3000;
http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('udx-worker-nodejs is running\n');
}).listen(port, () => {
  console.log(`Server listening on ${port}`);
});
JS

⁠2) Define Services

kind: workerService
version: udx.io/worker-v1/service
services:
  - name: "api-server"
    command: "node /usr/src/app/server.js"
    autostart: true
    autorestart: true
    envs:
      - "PORT=3000"
      - "NODE_ENV=production"

Save this as .config/worker/services.yaml.

⁠3) Run the Container

docker run -d \
  --name my-node-worker \
  -p 3000:3000 \
  -v "$(pwd)/.config/worker:/home/udx/.config/worker:ro" \
  -v "$(pwd)/src:/usr/src/app" \
  usabilitydynamics/udx-worker-nodejs:latest

docker logs -f my-node-worker

⁠4) Inspect Services

docker exec my-node-worker worker service list
docker exec my-node-worker worker service logs api-server

⁠Simplified Deployment With Worker CLI

Use Worker Deploy (@udx/worker-deployment) to replace long docker run flags with a simple deploy.yml + worker run workflow. It keeps local and CI/CD runs consistent and reduces deployment setup overhead.

Installed CLI:

npm install -g @udx/worker-deployment
worker config
worker run

No-install (npx) mode:

npx @udx/worker-deployment worker config
npx @udx/worker-deployment worker run

If you prefer, you can also run the image directly with docker run.

Minimal deploy.yml:

kind: workerDeployConfig
version: udx.io/worker-v1/deploy
config:
  image: "usabilitydynamics/udx-worker-nodejs:latest"
  volumes:
    - "./.config/worker:/home/udx/.config/worker:ro"
    - "./src:/usr/src/app"

⁠Configuration Model

Runtime files (mounted inside container):

• /home/udx/.config/worker/worker.yaml (runtime config, env, secrets)
• /home/udx/.config/worker/services.yaml (long-running services)

Application files:

• /usr/src/app (your Node.js code)

⁠Supported Credential Env Vars

• AZURE_CREDS
• AWS_CREDS
• GCP_CREDS

Values can be JSON, Base64-encoded JSON, or a file path.

⁠Typical Use Cases

• Run Node.js background services with restart policies.
• Execute Node.js automation scripts in CI/CD pipelines.
• Standardize secure runtime behavior across dev, CI, and production.

⁠Documentation

• Worker docs: https://udx.dev/worker⁠
• Worker Node.js repo: https://github.com/udx/worker-nodejs⁠
• Base runtime docs: https://github.com/udx/worker/tree/latest/docs⁠
• Deployment config docs: https://github.com/udx/worker-deployment/blob/latest/docs/deploy-config.md⁠
• Docker Hub: https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs⁠

⁠License

MIT License. See https://github.com/udx/worker-nodejs/blob/latest/LICENSE⁠.