From 30cd024d2787eb16f89a84d156f2ca89781055fb Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:02:08 +0300 Subject: [PATCH 01/14] docs: add repo best practices snapshot --- best_practices/10_principles.md | 17 +++++++++++++++++ best_practices/20_delivery.md | 21 +++++++++++++++++++++ best_practices/30_governance.md | 11 +++++++++++ best_practices/90_evidence.md | 15 +++++++++++++++ best_practices/README.md | 10 ++++++++++ 5 files changed, 74 insertions(+) create mode 100644 best_practices/10_principles.md create mode 100644 best_practices/20_delivery.md create mode 100644 best_practices/30_governance.md create mode 100644 best_practices/90_evidence.md create mode 100644 best_practices/README.md diff --git a/best_practices/10_principles.md b/best_practices/10_principles.md new file mode 100644 index 0000000..f93d5ca --- /dev/null +++ b/best_practices/10_principles.md @@ -0,0 +1,17 @@ +# Principles and Architecture + +## Scope +Summarize architecture, design, environment strategy, and repository structure. + +## Practices +- Build on the `udx-worker` base image and keep this repo focused on Node.js runtime concerns. +- Treat the container as a Node.js runtime image: application code is mounted to `/usr/src/app`. +- Define long-running processes in `services.yaml` and mount it into `/home/udx/.config/worker` at runtime. +- Keep runtime behavior configurable through volume mounts and environment variables rather than rebuilding the image for each app. +- Use a stable Node.js major version in the image and validate it in tests. + +## Evidence +- /Users/jonyfq/git/udx/worker-nodejs/README.md +- /Users/jonyfq/git/udx/worker-nodejs/Dockerfile +- /Users/jonyfq/git/udx/worker-nodejs/src/examples/README.md +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/10_validate_environment.sh diff --git a/best_practices/20_delivery.md b/best_practices/20_delivery.md new file mode 100644 index 0000000..629d29f --- /dev/null +++ b/best_practices/20_delivery.md @@ -0,0 +1,21 @@ +# Delivery and Operations + +## Scope +Summarize CI/CD, testing, release process, and runtime operations. + +## Practices +- Use `make build` for Docker image builds and optional multi-platform builds via `buildx`. +- Use `make run` for standard container execution and `make run-it` for interactive debugging. +- Use `make run-all-tests` (or `make test`) to validate the runtime image using in-container tests. +- Include a readiness check for local runs that waits for the containerized app to return HTTP 200. +- Validate the runtime image with focused tests: Node.js version, task execution, and Worker service CLI behavior. +- Keep versioning consistent with CI configuration and branch-based increment rules. + +## Evidence +- /Users/jonyfq/git/udx/worker-nodejs/Makefile +- /Users/jonyfq/git/udx/worker-nodejs/Makefile.help +- /Users/jonyfq/git/udx/worker-nodejs/Makefile.variables +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/10_validate_environment.sh +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/20_run_task_test.sh +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/30_validate_worker_service_cli.sh +- /Users/jonyfq/git/udx/worker-nodejs/ci/git-version.yml diff --git a/best_practices/30_governance.md b/best_practices/30_governance.md new file mode 100644 index 0000000..39a6fc4 --- /dev/null +++ b/best_practices/30_governance.md @@ -0,0 +1,11 @@ +# Governance and Security + +## Scope +Summarize security posture, permissions, compliance cues, data handling, and policy conventions. + +## Practices +- Provide a clear security reporting path and follow responsible disclosure before public release. +- Publish supported version expectations and contact information for security issues. + +## Evidence +- /Users/jonyfq/git/udx/worker-nodejs/SECURITY.md diff --git a/best_practices/90_evidence.md b/best_practices/90_evidence.md new file mode 100644 index 0000000..31ea28c --- /dev/null +++ b/best_practices/90_evidence.md @@ -0,0 +1,15 @@ +# Evidence Index + +List the primary sources used to derive best practices. + +- /Users/jonyfq/git/udx/worker-nodejs/README.md: image purpose, runtime usage, service configuration, volume mounts. +- /Users/jonyfq/git/udx/worker-nodejs/Dockerfile: base image, Node.js runtime install, app path. +- /Users/jonyfq/git/udx/worker-nodejs/Makefile: build/run/test workflow and readiness checks. +- /Users/jonyfq/git/udx/worker-nodejs/Makefile.help: supported Make targets and variables. +- /Users/jonyfq/git/udx/worker-nodejs/Makefile.variables: build/run defaults and port settings. +- /Users/jonyfq/git/udx/worker-nodejs/src/examples/README.md: services.yaml usage and volume mount pattern. +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/10_validate_environment.sh: Node.js version validation. +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/20_run_task_test.sh: runtime task execution check. +- /Users/jonyfq/git/udx/worker-nodejs/src/tests/30_validate_worker_service_cli.sh: Worker service CLI validation. +- /Users/jonyfq/git/udx/worker-nodejs/SECURITY.md: vulnerability reporting and disclosure. +- /Users/jonyfq/git/udx/worker-nodejs/ci/git-version.yml: versioning scheme. diff --git a/best_practices/README.md b/best_practices/README.md new file mode 100644 index 0000000..1b476f4 --- /dev/null +++ b/best_practices/README.md @@ -0,0 +1,10 @@ +# Best Practices + +Normalized best practices derived from this repo (`/Users/jonyfq/git/udx/worker-nodejs`). +These are intended to be reusable across projects that build on the same image pattern. + +## Files +- 10_principles.md +- 20_delivery.md +- 30_governance.md +- 90_evidence.md From b4137125ad3e40d8ee9b354ac459329a6c7210f4 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:02:14 +0300 Subject: [PATCH 02/14] examples: add worker-deployment templates --- deploy.yml | 19 +++++++++++++++++++ src/examples/README.md | 8 ++++++++ .../.config/worker/services.yaml | 3 ++- src/examples/simple-server/deploy.yml | 16 ++++++++++++++++ 4 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 deploy.yml create mode 100644 src/examples/simple-server/deploy.yml diff --git a/deploy.yml b/deploy.yml new file mode 100644 index 0000000..911b53b --- /dev/null +++ b/deploy.yml @@ -0,0 +1,19 @@ +# npm install -g @udx/worker-deployment +# worker config +# worker run + +--- +kind: workerDeployConfig +version: udx.io/worker-v1/deploy +config: + image: "usabilitydynamics/udx-worker-nodejs:latest" + + # Volume mounts (optional) + # Format: "host_path:container_path" or "host_path:container_path:ro" + volumes: + - "./src/examples/simple-server:/usr/src/app" + - "./src/examples/simple-server/.config/worker:/home/udx/.config/worker:ro" + + # Ports to expose (optional) + ports: + - "8080:8080" diff --git a/src/examples/README.md b/src/examples/README.md index 7d63789..457cced 100644 --- a/src/examples/README.md +++ b/src/examples/README.md @@ -49,6 +49,14 @@ services: - "8080:8080" ``` +3. Using worker-deployment: +```bash +npm install -g @udx/worker-deployment +cd src/examples +cp simple-server/deploy.yml deploy.yml +worker run +``` + ## 📁 Directory Structure Each example follows this structure: ``` diff --git a/src/examples/simple-server/.config/worker/services.yaml b/src/examples/simple-server/.config/worker/services.yaml index 0e429aa..576e467 100644 --- a/src/examples/simple-server/.config/worker/services.yaml +++ b/src/examples/simple-server/.config/worker/services.yaml @@ -1,4 +1,3 @@ ---- kind: workerService version: udx.io/worker-v1/service @@ -7,3 +6,5 @@ services: command: "node /usr/src/app/index.js" autostart: true autorestart: true + envs: + - "APP_PORT=8080" diff --git a/src/examples/simple-server/deploy.yml b/src/examples/simple-server/deploy.yml new file mode 100644 index 0000000..ed8f4e7 --- /dev/null +++ b/src/examples/simple-server/deploy.yml @@ -0,0 +1,16 @@ +# npm install -g @udx/worker-deployment +# worker config +# worker run + +--- +kind: workerDeployConfig +version: udx.io/worker-v1/deploy +config: + image: "usabilitydynamics/udx-worker-nodejs:latest" + + volumes: + - "./simple-server:/usr/src/app" + - "./simple-server/.config/worker:/home/udx/.config/worker:ro" + + ports: + - "8080:8080" From 908b1833f27cf9113116ac4f4fbfc55b2a4232de Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:02:21 +0300 Subject: [PATCH 03/14] ci: add test workflow and run-test target --- .github/workflows/tests.yml | 21 +++++++++++++++++++++ Makefile | 22 +++++++++++++++++++++- Makefile.help | 3 ++- Makefile.variables | 1 + 4 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/tests.yml diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..afd7235 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,21 @@ +--- +name: Tests + +on: + push: + pull_request: + +permissions: + contents: read + +jobs: + test: + name: Build and Test + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v6 + + - name: Build image and run tests + run: make test diff --git a/Makefile b/Makefile index 2a563d7..cc1def1 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ include Makefile.help .DEFAULT_GOAL := help # Phony targets ensure Make doesn't get confused by filenames -.PHONY: build run deploy run-it clean exec log test dev-pipeline run-all-tests wait-container-ready +.PHONY: build run deploy run-it clean exec log test dev-pipeline run-all-tests run-test wait-container-ready # Docker Commands for Reusability DOCKER_RUN_BASE := docker run --rm --name $(CONTAINER_NAME) \ @@ -42,6 +42,11 @@ run: clean @$(MAKE) wait-container-ready @echo "Container started successfully." +# Deploy Docker container (production mode) +deploy: clean + @echo "Deploying Docker container (production mode)..." + @$(MAKE) run NODE_ENV=production + # Run Docker container in interactive mode run-it: $(MAKE) run INTERACTIVE=true CMD="/bin/bash" @@ -90,6 +95,21 @@ run-all-tests: sh ./$$test_script || { echo "Test $$test_script failed"; exit 1; }; \ done' +# Run a specific test script +run-test: + @if [ -z "$(TEST_SCRIPT)" ]; then \ + echo "TEST_SCRIPT is required (e.g., make run-test TEST_SCRIPT=10_validate_environment.sh)"; \ + exit 1; \ + fi + @echo "Running test $(TEST_SCRIPT) in Docker container..." + @docker run --rm \ + -v $(PWD)/src/tests:/usr/src/app/tests \ + -v $(PWD)/src/examples/simple-server/index.js:/usr/src/app/index.js \ + -v $(PWD)/src/examples/simple-server/.config/worker/services.yaml:/home/udx/.config/worker/services.yaml \ + -e NODE_ENV=test \ + $(DOCKER_IMAGE) \ + /bin/sh -c 'cd /usr/src/app/tests && sh ./$(TEST_SCRIPT)' + # Run validation tests (build and run-all-tests) test: build run-all-tests @echo "Validation tests completed." diff --git a/Makefile.help b/Makefile.help index 8d33bd6..088feb2 100644 --- a/Makefile.help +++ b/Makefile.help @@ -27,5 +27,6 @@ help: @echo " BUILD_PLATFORMS = $(BUILD_PLATFORMS) # Platforms for multi-platform builds" @echo " NO_CACHE = $(NO_CACHE) # Disable cache when building Docker images" @echo " DETACHED = $(DETACHED) # Run containers in detached mode by default" - @echo " CMD = $(CMD) # Default command to run inside the container\n" + @echo " CMD = $(CMD) # Default command to run inside the container" + @echo " TEST_SCRIPT = $(TEST_SCRIPT) # Test script to run with run-test\n" @echo "To run a specific test with run-test, set the TEST_SCRIPT variable, e.g., 'make run-test TEST_SCRIPT=10_validate_environment.sh'" diff --git a/Makefile.variables b/Makefile.variables index 8070489..dfd4456 100644 --- a/Makefile.variables +++ b/Makefile.variables @@ -24,3 +24,4 @@ NO_CACHE ?= false # Runtime Options DETACHED ?= true CMD ?= /bin/bash +TEST_SCRIPT ?= From 1c5430dd70460838c77748e1dfcf3ce44afbf9d6 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:02:27 +0300 Subject: [PATCH 04/14] docs: update README examples and workflow --- README.md | 46 +++++++++++++++++++++++++++------------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 4bae580..f1e3421 100644 --- a/README.md +++ b/README.md @@ -27,25 +27,15 @@ UDX Worker Node.js is a specialized Docker image built on UDX Worker that provid ### Example 1: Simple Service -1. Create a service configuration in `.config/worker/services.yaml`: - -```yaml -kind: workerService -version: udx.io/worker-v1/service -services: - - name: "node-app" - command: "node index.js" - autostart: true - autorestart: true - envs: - - "PORT=3000" -``` - -2. Pull and run the image: +1. Use the included example in `src/examples/simple-server`: ```bash docker pull usabilitydynamics/udx-worker-nodejs:latest -docker run -d --name my-node-app -p 3000:3000 -v $(pwd)/.config:/home/udx/.config usabilitydynamics/udx-worker-nodejs:latest +docker run -d --name my-node-app \ + -v $(pwd)/src/examples/simple-server:/usr/src/app \ + -v $(pwd)/src/examples/simple-server/.config:/home/udx/.config \ + -p 8080:8080 \ + usabilitydynamics/udx-worker-nodejs:latest ``` ### Example 2: Custom Application @@ -102,16 +92,22 @@ make build 3. Run Tests to verify functionality: ``` -make run-all-tests +make test ``` You can add additional tests in the `src/tests/` directory as needed. +To run a single test: + +``` +make run-test TEST_SCRIPT=10_validate_environment.sh +``` ## ⚙️ Configuration You can configure build and runtime variables in `Makefile.variables`: -- Node.js version. _(Node.js 20.x LTS supported by default)_ +- Node.js version. _(Node.js 22.x LTS supported by default)_ +- To override, set `NODE_VERSION` as a build arg. - Port mappings - Source paths @@ -133,6 +129,18 @@ These commands offer options for building, running, and testing your application Built on [`udx-worker`](https://github.com/udx/worker), this image benefits from secure, resource-efficient configurations and best practices, providing a reliable foundation for Node.js applications. +### 🚚 worker-deployment CLI + +Use `@udx/worker-deployment` to standardize runs with a `deploy.yml` file: + +```bash +npm install -g @udx/worker-deployment +worker config +worker run +``` + +This repo includes a `deploy.yml` template and an example at `src/examples/simple-server/deploy.yml`. + ### Core Concepts - **Process Management**: Uses supervisor-based worker process manager @@ -182,4 +190,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ---
Built by UDX © 2025 -
\ No newline at end of file + From ef0af322ed3a229511ead1f81f667fc53f9779f8 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:02:34 +0300 Subject: [PATCH 05/14] build: bump udx-worker base image to 0.37.0 --- Dockerfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 07ea42b..a54cb77 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ # Use the latest udx-worker as the base image -FROM usabilitydynamics/udx-worker:0.36.0 +FROM usabilitydynamics/udx-worker:0.37.0 # Add metadata labels LABEL version="0.24.0" @@ -75,4 +75,4 @@ WORKDIR "${APP_HOME}" ENTRYPOINT ["/usr/local/worker/bin/entrypoint.sh"] # Use the default command from parent image -CMD ["tail", "-f", "/dev/null"] \ No newline at end of file +CMD ["tail", "-f", "/dev/null"] From 84e5f57b8771b43c8891dfacb589ed56e6b45a72 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:02:39 +0300 Subject: [PATCH 06/14] chore: add context7 config --- context7.json | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 context7.json diff --git a/context7.json b/context7.json new file mode 100644 index 0000000..d070aaf --- /dev/null +++ b/context7.json @@ -0,0 +1,4 @@ +{ + "url": "https://context7.com/udx/worker-nodejs", + "public_key": "pk_tqqni3hp1kYeoqIpnEaIp" +} From 72418cb963c204ea7a4755bb027943126bcab162 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:20:15 +0300 Subject: [PATCH 07/14] chore: remove best_practices snapshot --- best_practices/10_principles.md | 17 ----------------- best_practices/20_delivery.md | 21 --------------------- best_practices/30_governance.md | 11 ----------- best_practices/90_evidence.md | 15 --------------- best_practices/README.md | 10 ---------- 5 files changed, 74 deletions(-) delete mode 100644 best_practices/10_principles.md delete mode 100644 best_practices/20_delivery.md delete mode 100644 best_practices/30_governance.md delete mode 100644 best_practices/90_evidence.md delete mode 100644 best_practices/README.md diff --git a/best_practices/10_principles.md b/best_practices/10_principles.md deleted file mode 100644 index f93d5ca..0000000 --- a/best_practices/10_principles.md +++ /dev/null @@ -1,17 +0,0 @@ -# Principles and Architecture - -## Scope -Summarize architecture, design, environment strategy, and repository structure. - -## Practices -- Build on the `udx-worker` base image and keep this repo focused on Node.js runtime concerns. -- Treat the container as a Node.js runtime image: application code is mounted to `/usr/src/app`. -- Define long-running processes in `services.yaml` and mount it into `/home/udx/.config/worker` at runtime. -- Keep runtime behavior configurable through volume mounts and environment variables rather than rebuilding the image for each app. -- Use a stable Node.js major version in the image and validate it in tests. - -## Evidence -- /Users/jonyfq/git/udx/worker-nodejs/README.md -- /Users/jonyfq/git/udx/worker-nodejs/Dockerfile -- /Users/jonyfq/git/udx/worker-nodejs/src/examples/README.md -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/10_validate_environment.sh diff --git a/best_practices/20_delivery.md b/best_practices/20_delivery.md deleted file mode 100644 index 629d29f..0000000 --- a/best_practices/20_delivery.md +++ /dev/null @@ -1,21 +0,0 @@ -# Delivery and Operations - -## Scope -Summarize CI/CD, testing, release process, and runtime operations. - -## Practices -- Use `make build` for Docker image builds and optional multi-platform builds via `buildx`. -- Use `make run` for standard container execution and `make run-it` for interactive debugging. -- Use `make run-all-tests` (or `make test`) to validate the runtime image using in-container tests. -- Include a readiness check for local runs that waits for the containerized app to return HTTP 200. -- Validate the runtime image with focused tests: Node.js version, task execution, and Worker service CLI behavior. -- Keep versioning consistent with CI configuration and branch-based increment rules. - -## Evidence -- /Users/jonyfq/git/udx/worker-nodejs/Makefile -- /Users/jonyfq/git/udx/worker-nodejs/Makefile.help -- /Users/jonyfq/git/udx/worker-nodejs/Makefile.variables -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/10_validate_environment.sh -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/20_run_task_test.sh -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/30_validate_worker_service_cli.sh -- /Users/jonyfq/git/udx/worker-nodejs/ci/git-version.yml diff --git a/best_practices/30_governance.md b/best_practices/30_governance.md deleted file mode 100644 index 39a6fc4..0000000 --- a/best_practices/30_governance.md +++ /dev/null @@ -1,11 +0,0 @@ -# Governance and Security - -## Scope -Summarize security posture, permissions, compliance cues, data handling, and policy conventions. - -## Practices -- Provide a clear security reporting path and follow responsible disclosure before public release. -- Publish supported version expectations and contact information for security issues. - -## Evidence -- /Users/jonyfq/git/udx/worker-nodejs/SECURITY.md diff --git a/best_practices/90_evidence.md b/best_practices/90_evidence.md deleted file mode 100644 index 31ea28c..0000000 --- a/best_practices/90_evidence.md +++ /dev/null @@ -1,15 +0,0 @@ -# Evidence Index - -List the primary sources used to derive best practices. - -- /Users/jonyfq/git/udx/worker-nodejs/README.md: image purpose, runtime usage, service configuration, volume mounts. -- /Users/jonyfq/git/udx/worker-nodejs/Dockerfile: base image, Node.js runtime install, app path. -- /Users/jonyfq/git/udx/worker-nodejs/Makefile: build/run/test workflow and readiness checks. -- /Users/jonyfq/git/udx/worker-nodejs/Makefile.help: supported Make targets and variables. -- /Users/jonyfq/git/udx/worker-nodejs/Makefile.variables: build/run defaults and port settings. -- /Users/jonyfq/git/udx/worker-nodejs/src/examples/README.md: services.yaml usage and volume mount pattern. -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/10_validate_environment.sh: Node.js version validation. -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/20_run_task_test.sh: runtime task execution check. -- /Users/jonyfq/git/udx/worker-nodejs/src/tests/30_validate_worker_service_cli.sh: Worker service CLI validation. -- /Users/jonyfq/git/udx/worker-nodejs/SECURITY.md: vulnerability reporting and disclosure. -- /Users/jonyfq/git/udx/worker-nodejs/ci/git-version.yml: versioning scheme. diff --git a/best_practices/README.md b/best_practices/README.md deleted file mode 100644 index 1b476f4..0000000 --- a/best_practices/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Best Practices - -Normalized best practices derived from this repo (`/Users/jonyfq/git/udx/worker-nodejs`). -These are intended to be reusable across projects that build on the same image pattern. - -## Files -- 10_principles.md -- 20_delivery.md -- 30_governance.md -- 90_evidence.md From 4ac900c26b9066495d4122c6c97274a6dc3ac56c Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:20:21 +0300 Subject: [PATCH 08/14] build: dedupe test targets --- Makefile | 28 ++++++++++++---------------- Makefile.help | 6 +++--- 2 files changed, 15 insertions(+), 19 deletions(-) diff --git a/Makefile b/Makefile index cc1def1..f0cbee6 100644 --- a/Makefile +++ b/Makefile @@ -22,6 +22,12 @@ endif DOCKER_EXEC := docker exec -it $(CONTAINER_NAME) DOCKER_CLEAN := docker rm -f $(CONTAINER_NAME) || true +TEST_VOLUMES := \ + -v $(PWD)/src/tests:/usr/src/app/tests \ + -v $(PWD)/src/examples/simple-server/index.js:/usr/src/app/index.js \ + -v $(PWD)/src/examples/simple-server/.config/worker/services.yaml:/home/udx/.config/worker/services.yaml +TEST_ENV := -e NODE_ENV=test +TEST_RUN := docker run --rm $(TEST_VOLUMES) $(TEST_ENV) $(DOCKER_IMAGE) # Build the Docker image with multi-platform support build: @@ -82,38 +88,28 @@ wait-container-ready: @echo "Container is ready." # Run all tests in the tests directory -run-all-tests: +run-all-tests: build @echo "Running all tests in Docker container..." - @docker run --rm \ - -v $(PWD)/src/tests:/usr/src/app/tests \ - -v $(PWD)/src/examples/simple-server/index.js:/usr/src/app/index.js \ - -v $(PWD)/src/examples/simple-server/.config/worker/services.yaml:/home/udx/.config/worker/services.yaml \ - -e NODE_ENV=test \ - $(DOCKER_IMAGE) \ + @$(TEST_RUN) \ /bin/sh -c 'cd /usr/src/app/tests && for test_script in *.sh; do \ echo "Running $$test_script..."; \ sh ./$$test_script || { echo "Test $$test_script failed"; exit 1; }; \ done' # Run a specific test script -run-test: +run-test: build @if [ -z "$(TEST_SCRIPT)" ]; then \ echo "TEST_SCRIPT is required (e.g., make run-test TEST_SCRIPT=10_validate_environment.sh)"; \ exit 1; \ fi @echo "Running test $(TEST_SCRIPT) in Docker container..." - @docker run --rm \ - -v $(PWD)/src/tests:/usr/src/app/tests \ - -v $(PWD)/src/examples/simple-server/index.js:/usr/src/app/index.js \ - -v $(PWD)/src/examples/simple-server/.config/worker/services.yaml:/home/udx/.config/worker/services.yaml \ - -e NODE_ENV=test \ - $(DOCKER_IMAGE) \ + @$(TEST_RUN) \ /bin/sh -c 'cd /usr/src/app/tests && sh ./$(TEST_SCRIPT)' # Run validation tests (build and run-all-tests) -test: build run-all-tests +test: run-all-tests @echo "Validation tests completed." # Development pipeline (build and test) -dev-pipeline: build test +dev-pipeline: test @echo "Development pipeline completed successfully." diff --git a/Makefile.help b/Makefile.help index 088feb2..71deedf 100644 --- a/Makefile.help +++ b/Makefile.help @@ -9,9 +9,9 @@ help: @echo " clean Stop and remove any existing container with the specified name" @echo " wait-container-ready Wait for the container to be ready by checking application readiness" @echo " run-test Run a specific test script in the test environment (requires TEST_SCRIPT variable)" - @echo " run-all-tests Run all test scripts in the tests directory with a test environment" - @echo " test Run validation tests (build and run-all-tests)" - @echo " dev-pipeline Execute the full development pipeline (build and test)\n" + @echo " run-all-tests Build the image and run all test scripts" + @echo " test Run validation tests (same as run-all-tests)" + @echo " dev-pipeline Execute the validation pipeline\n" @echo "Variables (with default values):\n" @echo " IMAGE_NAME = $(IMAGE_NAME) # Name of the Docker image" @echo " TAG = $(TAG) # Tag for the Docker image" From 0c321dccbd654f8b482c30c08bf875c000541b3c Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:20:24 +0300 Subject: [PATCH 09/14] docs: add logo and fix clone instructions --- README.md | 6 ++++-- assets/logo.svg | 50 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 2 deletions(-) create mode 100644 assets/logo.svg diff --git a/README.md b/README.md index f1e3421..438cc5c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +UDX Worker Node.js + # UDX Worker Node.js [![Docker Pulls](https://img.shields.io/docker/pulls/usabilitydynamics/udx-worker-nodejs.svg)](https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs) [![License](https://img.shields.io/github/license/udx/worker-nodejs.svg)](LICENSE) @@ -79,8 +81,8 @@ services: 1. Clone this repository: ``` -git clone https://github.com/udx/udx-worker-nodejs.git -cd udx-worker-nodejs +git clone https://github.com/udx/worker-nodejs.git +cd worker-nodejs ``` 2. Build the Docker image: diff --git a/assets/logo.svg b/assets/logo.svg new file mode 100644 index 0000000..95ec6d0 --- /dev/null +++ b/assets/logo.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From ae188dbce7194072f58bf6580915dc6138128830 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:21:18 +0300 Subject: [PATCH 10/14] bump version --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index a54cb77..b5723f1 100644 --- a/Dockerfile +++ b/Dockerfile @@ -2,7 +2,7 @@ FROM usabilitydynamics/udx-worker:0.37.0 # Add metadata labels -LABEL version="0.24.0" +LABEL version="0.25.0" # Set build arguments for Node.js version and application port ARG NODE_VERSION=22.21.1 From 4b7be867398b5642d6a05f3d39ca5eacb363517f Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 19:27:17 +0300 Subject: [PATCH 11/14] docs: streamline README --- README.md | 148 ++++++++++++++---------------------------------------- 1 file changed, 39 insertions(+), 109 deletions(-) diff --git a/README.md b/README.md index 438cc5c..5462e11 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,24 @@ [![Docker Pulls](https://img.shields.io/docker/pulls/usabilitydynamics/udx-worker-nodejs.svg)](https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs) [![License](https://img.shields.io/github/license/udx/worker-nodejs.svg)](LICENSE) -**A versatile Docker image for running Node.js applications with built-in process management, providing a ready-to-use environment to deploy and manage your JavaScript projects.** +**Node.js runtime image built on UDX Worker with supervisor-based process management.** -[Quick Start](#-quick-start) • [Development](#-development) • [Documentation](#-documentation) • [Contributing](#-contributing) +[Quick Start](#-quick-start) • [Usage](#-usage) • [Development](#-development) • [Resources](#-resources) ## 🚀 Overview -UDX Worker Node.js is a specialized Docker image built on UDX Worker that provides: +UDX Worker Node.js provides: -- 🔧 **Node.js Runtime**: Ready-to-use environment for JavaScript applications -- 📦 **Process Management**: Built-in supervisor-based service management -- 🛠️ **Service Configuration**: YAML-based service definition and control -- 🔄 **Zero Downtime**: Seamless application updates and restarts -- 🏗️ **Base Image**: Built on `udx-worker` for secure, efficient operations +- 🔧 **Node.js Runtime**: Ready-to-use environment for JavaScript apps +- 📦 **Process Management**: Supervisor-based service lifecycle +- 🛠️ **Service Configuration**: `services.yaml` for runtime services +- 🏗️ **Base Image**: Built on `udx-worker` for consistent ops -## 👨‍💻 Development +## 🏃 Quick Start -### 📋 Prerequisites +### Example: Simple Service -- `Docker` installed and running on your system -- Node.js application code (optional) - -## 🚀 Quick Start - -### Example 1: Simple Service - -1. Use the included example in `src/examples/simple-server`: +Use the included example in `src/examples/simple-server`: ```bash docker pull usabilitydynamics/udx-worker-nodejs:latest @@ -40,9 +32,9 @@ docker run -d --name my-node-app \ usabilitydynamics/udx-worker-nodejs:latest ``` -### Example 2: Custom Application +### Example: Custom Application -1. Create your service configuration in `.config/worker/services.yaml`: +1. Create `.config/worker/services.yaml`: ```yaml kind: workerService @@ -55,14 +47,9 @@ services: envs: - "PORT=3000" - "NODE_ENV=production" - - name: "worker-queue" - command: "node worker.js" - autostart: true - envs: - - "QUEUE_URL=redis://localhost:6379" ``` -2. Create a `docker-compose.yml`: +2. Run with Docker Compose: ```yaml version: '3' @@ -76,95 +63,53 @@ services: - "3000:3000" ``` -### Development Setup - -1. Clone this repository: - -``` -git clone https://github.com/udx/worker-nodejs.git -cd worker-nodejs -``` - -2. Build the Docker image: +## ⚙️ Usage -``` -make build -``` +### worker-deployment CLI -3. Run Tests to verify functionality: +Use `@udx/worker-deployment` to standardize runs with `deploy.yml`: -``` -make test +```bash +npm install -g @udx/worker-deployment +worker config +worker run ``` -You can add additional tests in the `src/tests/` directory as needed. -To run a single test: +This repo includes: +- `deploy.yml` (root template) +- `src/examples/simple-server/deploy.yml` (example) -``` -make run-test TEST_SCRIPT=10_validate_environment.sh -``` +### Configuration -## ⚙️ Configuration +Runtime and build variables live in `Makefile.variables`: -You can configure build and runtime variables in `Makefile.variables`: - -- Node.js version. _(Node.js 22.x LTS supported by default)_ -- To override, set `NODE_VERSION` as a build arg. +- Node.js version (default `22.x LTS`) - Port mappings - Source paths -Adjust these variables to suit your environment or specific deployment requirements. - -## 🛠️ Makefile Commands Helper +## 🛠️ Development -Use make to view all available commands: +```bash +git clone https://github.com/udx/worker-nodejs.git +cd worker-nodejs +make build +make test ``` -make help -``` - -These commands offer options for building, running, and testing your application seamlessly. -## 📚 Documentation - -### 🔧 Based on udx-worker - -Built on [`udx-worker`](https://github.com/udx/worker), this image benefits from secure, resource-efficient configurations and best practices, providing a reliable foundation for Node.js applications. - -### 🚚 worker-deployment CLI - -Use `@udx/worker-deployment` to standardize runs with a `deploy.yml` file: +To run a single test: ```bash -npm install -g @udx/worker-deployment -worker config -worker run +make run-test TEST_SCRIPT=10_validate_environment.sh ``` -This repo includes a `deploy.yml` template and an example at `src/examples/simple-server/deploy.yml`. - -### Core Concepts - -- **Process Management**: Uses supervisor-based worker process manager -- **Service Configuration**: Defined through `services.yaml` -- **Configuration**: Customizable through `Makefile.variables` +## 📚 Resources -### Additional Resources - -- Build variables can be configured in `Makefile.variables` -- View available commands with `make help` -- Test examples available in `src/tests/` - -## 🛠️ Development - -Contribute to the project: - -1. Fork the repository -2. Create your feature branch -3. Submit a pull request +- Base image docs: `udx/worker` — https://github.com/udx/worker +- Docker Hub: https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs +- Product page: https://udx.io/products/udx-worker-nodejs ## 🤝 Contributing -We welcome contributions! Here's how you can help: 1. Fork the repository 2. Create a feature branch @@ -172,22 +117,7 @@ We welcome contributions! Here's how you can help: 4. Push to your branch 5. Open a Pull Request -Please ensure your PR: -- Follows our coding standards -- Includes appropriate tests -- Updates relevant documentation - -## 🔗 Resources -- [Docker Hub](https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs) -- [UDX Worker Documentation](https://github.com/udx/worker) -- [Product Page](https://udx.io/products/udx-worker-nodejs) - -## 🎯 Custom Development -Need specific features or customizations? -[Contact our team](https://udx.io/) for professional development services. - -## 📄 License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +Please ensure your PR includes appropriate tests and documentation updates. ---
From 3493c1225edb24ce78277dcf58d89258c1495ce5 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 20:02:27 +0300 Subject: [PATCH 12/14] docs: refine README --- README.md | 106 +++++++++++++++++++++--------------------------------- 1 file changed, 41 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 5462e11..59bdb9f 100644 --- a/README.md +++ b/README.md @@ -4,90 +4,62 @@ [![Docker Pulls](https://img.shields.io/docker/pulls/usabilitydynamics/udx-worker-nodejs.svg)](https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs) [![License](https://img.shields.io/github/license/udx/worker-nodejs.svg)](LICENSE) -**Node.js runtime image built on UDX Worker with supervisor-based process management.** +**Node.js runtime image built on UDX Worker.** -[Quick Start](#-quick-start) • [Usage](#-usage) • [Development](#-development) • [Resources](#-resources) +[Quick Start](#quick-start) • [Usage](#usage) • [Development](#development) • [Resources](#resources) -## 🚀 Overview +## Overview -UDX Worker Node.js provides: +UDX Worker Node.js is a Docker image that provides a ready-to-use Node.js runtime with the same operational model as `udx/worker` (https://github.com/udx/worker). This repository contains the image source; most users run the published image via `@udx/worker-deployment`. -- 🔧 **Node.js Runtime**: Ready-to-use environment for JavaScript apps -- 📦 **Process Management**: Supervisor-based service lifecycle -- 🛠️ **Service Configuration**: `services.yaml` for runtime services -- 🏗️ **Base Image**: Built on `udx-worker` for consistent ops +## Quick Start -## 🏃 Quick Start +Requirements: Docker and Node.js (for the CLI). -### Example: Simple Service - -Use the included example in `src/examples/simple-server`: +1. Install the deployment CLI (`@udx/worker-deployment`). ```bash -docker pull usabilitydynamics/udx-worker-nodejs:latest -docker run -d --name my-node-app \ - -v $(pwd)/src/examples/simple-server:/usr/src/app \ - -v $(pwd)/src/examples/simple-server/.config:/home/udx/.config \ - -p 8080:8080 \ - usabilitydynamics/udx-worker-nodejs:latest +npm install -g @udx/worker-deployment ``` -### Example: Custom Application - -1. Create `.config/worker/services.yaml`: - -```yaml -kind: workerService -version: udx.io/worker-v1/service -services: - - name: "api-server" - command: "node api/server.js" - autostart: true - autorestart: true - envs: - - "PORT=3000" - - "NODE_ENV=production" -``` +2. Generate a config and edit `deploy.yml` for your app. -2. Run with Docker Compose: - -```yaml -version: '3' -services: - app: - image: usabilitydynamics/udx-worker-nodejs:latest - volumes: - - ./:/usr/src/app - - ./.config:/home/udx/.config - ports: - - "3000:3000" +```bash +worker config ``` -## ⚙️ Usage - -### worker-deployment CLI - -Use `@udx/worker-deployment` to standardize runs with `deploy.yml`: +3. Run the container. ```bash -npm install -g @udx/worker-deployment -worker config worker run ``` -This repo includes: -- `deploy.yml` (root template) -- `src/examples/simple-server/deploy.yml` (example) +Notes: +- `worker config` generates a `deploy.yml` in your current directory. +- Edit `deploy.yml` with your settings before running. +- Deploy config format and CLI reference: https://github.com/udx/worker/tree/main/docs/deploy/README.md +- `@udx/worker-deployment` on GitHub: https://github.com/udx/worker-deployment +- `@udx/worker-deployment` on npm: https://www.npmjs.com/package/@udx/worker-deployment + +## Usage + +### Deployment Configuration + +- `deploy.yml` is the primary entrypoint for running this image. +- Schema and CLI behavior: https://github.com/udx/worker/tree/main/docs/deploy/README.md -### Configuration +### Runtime Services -Runtime and build variables live in `Makefile.variables`: +- Define services in `.config/worker/services.yaml`. +- Service configuration: https://github.com/udx/worker/tree/main/docs/runtime/services.md -- Node.js version (default `22.x LTS`) -- Port mappings -- Source paths +### Runtime Config and Secrets -## 🛠️ Development +- Define runtime config in `.config/worker/worker.yaml`. +- Runtime config and auth providers: https://github.com/udx/worker/tree/main/docs/runtime/config.md +- Authorization details: https://github.com/udx/worker/tree/main/docs/authorization.md + +## Development ```bash git clone https://github.com/udx/worker-nodejs.git @@ -103,13 +75,16 @@ To run a single test: make run-test TEST_SCRIPT=10_validate_environment.sh ``` -## 📚 Resources +Build defaults for contributors live in `Makefile.variables` (Node.js version, ports, build args). + +## Resources -- Base image docs: `udx/worker` — https://github.com/udx/worker +- Base image docs: https://github.com/udx/worker +- Deployment CLI: https://github.com/udx/worker-deployment - Docker Hub: https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs - Product page: https://udx.io/products/udx-worker-nodejs -## 🤝 Contributing +## Contributing 1. Fork the repository 2. Create a feature branch @@ -120,6 +95,7 @@ make run-test TEST_SCRIPT=10_validate_environment.sh Please ensure your PR includes appropriate tests and documentation updates. --- +
Built by UDX © 2025
From b4262c62aba92d1e2d7a3873701fdfb1ed714d79 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 20:03:27 +0300 Subject: [PATCH 13/14] tweak --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 59bdb9f..6955cb3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ UDX Worker Node.js -# UDX Worker Node.js - [![Docker Pulls](https://img.shields.io/docker/pulls/usabilitydynamics/udx-worker-nodejs.svg)](https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs) [![License](https://img.shields.io/github/license/udx/worker-nodejs.svg)](LICENSE) **Node.js runtime image built on UDX Worker.** @@ -10,7 +8,7 @@ ## Overview -UDX Worker Node.js is a Docker image that provides a ready-to-use Node.js runtime with the same operational model as `udx/worker` (https://github.com/udx/worker). This repository contains the image source; most users run the published image via `@udx/worker-deployment`. +UDX Worker Node.js is a Docker image that provides a ready-to-use Node.js runtime with the same operational model as `udx/worker` (https://github.com/udx/worker). ## Quick Start @@ -35,6 +33,7 @@ worker run ``` Notes: + - `worker config` generates a `deploy.yml` in your current directory. - Edit `deploy.yml` with your settings before running. - Deploy config format and CLI reference: https://github.com/udx/worker/tree/main/docs/deploy/README.md From 466ddc9a71a3e08b38aba6d477ad321d0c071041 Mon Sep 17 00:00:00 2001 From: Dmitry Smirnov Date: Fri, 6 Feb 2026 20:13:20 +0300 Subject: [PATCH 14/14] update readme --- README.md | 31 ++++++++----------------------- 1 file changed, 8 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 6955cb3..4bd91db 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ UDX Worker Node.js is a Docker image that provides a ready-to-use Node.js runtim Requirements: Docker and Node.js (for the CLI). -1. Install the deployment CLI (`@udx/worker-deployment`). +1. Install the deployment CLI ([@udx/worker-deployment](https://www.npmjs.com/package/@udx/worker-deployment)). ```bash npm install -g @udx/worker-deployment @@ -32,31 +32,17 @@ worker config worker run ``` -Notes: - -- `worker config` generates a `deploy.yml` in your current directory. -- Edit `deploy.yml` with your settings before running. -- Deploy config format and CLI reference: https://github.com/udx/worker/tree/main/docs/deploy/README.md -- `@udx/worker-deployment` on GitHub: https://github.com/udx/worker-deployment -- `@udx/worker-deployment` on npm: https://www.npmjs.com/package/@udx/worker-deployment - ## Usage -### Deployment Configuration - -- `deploy.yml` is the primary entrypoint for running this image. -- Schema and CLI behavior: https://github.com/udx/worker/tree/main/docs/deploy/README.md +- Deploy configuration: https://github.com/udx/worker-deployment/blob/latest/docs/deploy-config.md -### Runtime Services +- Service configuration: https://github.com/udx/worker/blob/latest/docs/runtime/services.md -- Define services in `.config/worker/services.yaml`. -- Service configuration: https://github.com/udx/worker/tree/main/docs/runtime/services.md +- Runtime config and secrets: https://github.com/udx/worker/blob/latest/docs/runtime/config.md -### Runtime Config and Secrets +### Examples -- Define runtime config in `.config/worker/worker.yaml`. -- Runtime config and auth providers: https://github.com/udx/worker/tree/main/docs/runtime/config.md -- Authorization details: https://github.com/udx/worker/tree/main/docs/authorization.md +- `src/examples/simple-server` is included as a minimal sample. ## Development @@ -78,10 +64,9 @@ Build defaults for contributors live in `Makefile.variables` (Node.js version, p ## Resources -- Base image docs: https://github.com/udx/worker -- Deployment CLI: https://github.com/udx/worker-deployment +- Base image docs: https://github.com/udx/worker/tree/latest/docs +- Deployment CLI: https://github.com/udx/worker-deployment/tree/latest/docs - Docker Hub: https://hub.docker.com/r/usabilitydynamics/udx-worker-nodejs -- Product page: https://udx.io/products/udx-worker-nodejs ## Contributing