Refresh worker-php runtime docs and config contract

.rabbit/README.md

@@ -0,0 +1,41 @@
+# Rabbit CI
+
+This directory owns Rabbit-facing repo context for `udx/worker-php`.
+
+`worker-php` is a runtime image repo. It publishes the Docker image that PHP
+Worker-based applications can consume, but it does not own tenant-specific
+Rabbit lifecycle manifests or environment config.
+
+## Entry Points
+
+- Generated repo context: [`context.yaml`](./context.yaml)
+- Image release workflow: [`../.github/workflows/docker-ops.yml`](../.github/workflows/docker-ops.yml)
+- Worker config contract: [`../worker.yaml`](../worker.yaml)
+- Worker config reference: [`../docs/worker-config.md`](../docs/worker-config.md)
+- Runtime image contract: [`../Dockerfile`](../Dockerfile)
+
+## Rabbit Delivery Path
+
+1. Changes to `Dockerfile`, `bin/**`, `ci/**`, `etc/**`, `src/**`, or the
+   Docker workflow run the Docker operations workflow.
+2. The workflow delegates image build, scan, release, and publish behavior to
+   `udx/reusable-workflows`.
+3. The `latest` branch is the release branch for published `worker-php` images.
+4. Tenant repos reference the published image from their own Rabbit lifecycle
+   manifests or deployment config.
+5. Tenant runtime values and secrets belong in the tenant repo or target
+   platform. Image-level defaults and secret references belong in
+   [`../worker.yaml`](../worker.yaml).
+
+## Repo Context
+
+[`context.yaml`](./context.yaml) is generated by `dev.kit repo`. Do not edit it
+manually. Refresh it after changing repo-owned docs, manifests, workflows, or
+runtime contracts:
+
+```bash
+dev.kit repo
+```
+
+Review the generated context before relying on it in an agent session or Rabbit
+CI workflow.

.rabbit/context.yaml

@@ -5,8 +5,8 @@ version: udx.dev/dev.kit/v1
 generator:
   tool: dev.kit
   repo: https://github.com/udx/dev.kit
-  version: 0.14.0
-  generated_at: 2026-07-01T08:30:38Z
+  version: 0.20.0
+  generated_at: 2026-07-08T15:46:44Z
   sources:
     homepage: https://udx.dev/kit
     repository: https://github.com/udx/dev.kit
@@ -25,7 +25,7 @@ repo:
 refs:
   - ./README.md
   - ./Makefile
-  - ./deploy.yml
+  - ./worker.yaml
   - ./.github/workflows
   - ./Dockerfile
   - ./docs
@@ -56,25 +56,22 @@ dependencies:
     kind: reusable workflow
     resolved: true
     archetype: manifest-repo
-    description: Reusable GitHub Actions workflow templates for CI/CD
     used_by:
       - .github/workflows/docker-ops.yml
   - repo: usabilitydynamics/udx-worker:0.45.0
     kind: base image
     resolved: true
     source_repo: udx/worker
     archetype: manifest-repo
-    description: UDX Worker Docker image
     used_by:
       - Dockerfile
   - repo: udx/worker
-    kind: manifest contract (deploy)
+    kind: manifest contract (config)
     resolved: true
-    declared_as: udx.io/worker-v1/deploy
+    declared_as: udx.io/worker-v1/config
     archetype: manifest-repo
-    description: UDX Worker Docker image
     used_by:
-      - deploy.yml
+      - worker.yaml
 
 # Manifests — YAML files that define repo-specific workflow, deploy, or contract behavior.
 # Note: Include custom config/manifests that materially shape repo behavior or contract understanding.
@@ -86,12 +83,23 @@ dependencies:
 manifests:
   - path: .github/workflows/docker-ops.yml
     kind: githubWorkflow
-  - path: deploy.yml
-    kind: workerDeployConfig
-    declared_as: udx.io/worker-v1/deploy
+    used_by:
+      - .rabbit/README.md
+      - README.md
+    evidence:
+      - path reference: .rabbit/README.md
+      - path reference: README.md
+  - path: worker.yaml
+    kind: workerConfig
+    declared_as: udx.io/worker-v1/config
     source_repo: udx/worker
     used_by:
+      - .rabbit/README.md
       - README.md
+      - docs/worker-config.md
     evidence:
-      - version: udx.io/worker-v1/deploy
+      - version: udx.io/worker-v1/config
+      - github reference: udx/worker
+      - path reference: .rabbit/README.md
       - path reference: README.md
+      - path reference: docs/worker-config.md

Dockerfile

@@ -3,7 +3,6 @@ FROM usabilitydynamics/udx-worker:0.45.0
 
 # Add metadata labels
 LABEL maintainer="UDX"
-LABEL version="0.31.0"
 
 # Arguments and Environment Variables
 ARG PHP_VERSION=8.4

Makefile

@@ -90,9 +90,20 @@ wait-container-ready:
 	@printf "$(COLOR_GREEN)$(SYM_SUCCESS) Container is ready$(COLOR_RESET)\n"
 
 # Run a specific test script (specified by TEST_SCRIPT)
-run-test:
-	@echo "Running test script $(TEST_SCRIPT) ..."
-	@$(MAKE) run CMD="php $(CONTAINER_SRC_PATH)/tests/$(TEST_SCRIPT)"
+run-test: clean
+	@if [ ! -f "$(SRC_PATH)/tests/$(TEST_SCRIPT)" ]; then \
+		printf "$(COLOR_RED)$(SYM_ERROR) Test script not found: $(SRC_PATH)/tests/$(TEST_SCRIPT)$(COLOR_RESET)\n"; \
+		exit 1; \
+	fi
+	@printf "$(COLOR_BLUE)$(SYM_ARROW) Starting test container...$(COLOR_RESET)\n"
+	@docker run -d --rm --name $(CONTAINER_NAME) -v $(CURDIR)/$(SRC_PATH):$(CONTAINER_SRC_PATH) -p $(HOST_PORT):$(CONTAINER_PORT) $(DOCKER_IMAGE) || \
+		{ printf "$(COLOR_RED)$(SYM_ERROR) Failed to start test container$(COLOR_RESET)\n"; exit 1; }
+	@$(MAKE) wait-container-ready || { $(MAKE) clean; exit 1; }
+	@printf "$(COLOR_BLUE)$(SYM_ARROW) Running $(TEST_SCRIPT)...$(COLOR_RESET)\n"
+	@docker exec $(CONTAINER_NAME) php $(CONTAINER_SRC_PATH)/tests/$(TEST_SCRIPT) && \
+	printf "$(COLOR_GREEN)$(SYM_SUCCESS) Test $(TEST_SCRIPT) passed$(COLOR_RESET)\n" || \
+	{ printf "$(COLOR_RED)$(SYM_ERROR) Test $(TEST_SCRIPT) failed$(COLOR_RESET)\n"; $(MAKE) clean; exit 1; }
+	@$(MAKE) clean
 
 # Run all tests in the tests directory
 run-all-tests: clean

Makefile.variables

@@ -34,7 +34,7 @@ SRC_PATH := src
 CONTAINER_SRC_PATH := /var/www
 
 # Specific test script name
-TEST_SCRIPT := test.php
+TEST_SCRIPT := 10_nginx_test.php
 
 # Path for all test scripts
 TESTS_PATH := $(CONTAINER_SRC_PATH)/tests

README.md

@@ -3,158 +3,131 @@
 # UDX Worker PHP
 
 [![Docker Pulls](https://img.shields.io/docker/pulls/usabilitydynamics/udx-worker-php.svg)](https://hub.docker.com/r/usabilitydynamics/udx-worker-php)
+[![GitHub Release](https://img.shields.io/github/v/release/udx/worker-php?sort=semver)](https://github.com/udx/worker-php/releases/latest)
 [![License](https://img.shields.io/github/license/udx/worker-php.svg)](LICENSE)
 
-PHP runtime image built on UDX Worker with NGINX + PHP-FPM preconfigured.
+PHP runtime image built on UDX Worker with NGINX and PHP-FPM wired for `/var/www`.
 
-[Quick Start](#quick-start) • [Usage](#usage) • [Development](#development) • [Resources](#resources)
+[Quick Start](#quick-start) - [Runtime](#runtime) - [Development](#development) - [Deployment](#deployment) - [Rabbit CI](#rabbit-ci)
 
 ## Overview
 
-`udx-worker-php` extends [`udx/worker`](https://github.com/udx/worker) and keeps the same worker runtime model while adding:
+`udx-worker-php` extends [`udx/worker`](https://github.com/udx/worker), published as `usabilitydynamics/udx-worker`, and keeps the worker runtime model while adding a PHP web stack:
 
-- NGINX configured for `/var/www`
-- PHP-FPM (`8.4`) with socket-based NGINX integration
-- Worker service definitions that autostart both `php-fpm` and `nginx`
+- NGINX serves `/var/www`.
+- PHP-FPM runs behind NGINX through a Unix socket.
+- PHP CLI and common extensions are installed for application and automation workloads.
+- Worker service definitions start both `php-fpm` and `nginx`.
 
-This image is intended as a base runtime for PHP applications and PHP-focused automation workloads.
+Use this image as a base for PHP applications, automation jobs, or deployment workflows that need the Worker runtime contract.
 
 ## Quick Start
 
-Requirements: Docker (and Make if you want local dev commands).
+Requirements: Docker. Make is optional but recommended for local development.
 
-### Run from Docker Hub
+Run the published image:
 
 ```bash
 docker run -d \
   --name my-php-app \
-  -p 80:80 \
+  -p 8080:80 \
   -v "$(pwd)/my-php-app:/var/www" \
   usabilitydynamics/udx-worker-php:latest
 ```
 
-Then open `http://localhost` (or your mapped host port).
+Then open `http://localhost:8080`.
 
-### Local Development Workflow
+Build and run locally:
 
 ```bash
 git clone https://github.com/udx/worker-php.git
 cd worker-php
 
 make build
-make run
+make run HOST_PORT=8080
 make log FOLLOW_LOGS=true
 ```
 
-`make run` uses these defaults from `Makefile.variables`:
+`make run` uses defaults from `Makefile.variables`, including `./src/scripts:/var/www`, `.env`, and container port `80`.
 
-- volume: `./src/scripts:/var/www`
-- host/container port: `80:80`
-- env file: `.env`
+This image does not require default environment variables. Runtime environment values and secret references belong in `worker.yaml` or the target platform.
 
-## Usage
+## Runtime
 
-### Mount your own app code
+The runtime contract is defined by the Dockerfile and the configs copied into the image:
 
-```bash
-make run VOLUMES="$(pwd)/path-to-app:/var/www" HOST_PORT=8080
-```
+- `Dockerfile` pins the base Worker image and Ubuntu package versions.
+- `etc/configs/nginx/` defines the NGINX server and PHP FastCGI integration.
+- `etc/configs/php/` defines PHP-FPM process and pool behavior.
+- `etc/configs/worker/services.yaml` declares Worker-managed services.
 
-### Run interactively
+`/var/www` is both the declared volume and working directory. NGINX sends PHP requests to the PHP-FPM Unix socket configured during the image build.
 
-```bash
-make run-it
-```
+## Development
 
-### Execute into the running container
+Common commands:
 
 ```bash
+make help
+make build
+make run HOST_PORT=8080
 make exec
+make log
+make clean
 ```
 
-### Deploy with Worker CLI config
-
-This repo includes a sample `deploy.yml` for [`@udx/worker-deployment`](https://www.npmjs.com/package/@udx/worker-deployment).
+Run all validation:
 
 ```bash
-npm install -g @udx/worker-deployment
-worker run
+make test
 ```
 
-## Testing
-
-Run all built-in tests:
+Run only the container test suite against an already built image:
 
 ```bash
 make run-all-tests
 ```
 
-Run full validation (build + tests):
+Run one test script:
 
 ```bash
-make test
+make run-test TEST_SCRIPT=10_nginx_test.php
 ```
 
-Run a specific test script:
+Current tests live in `src/tests/` and cover NGINX HTTP response, PHP runtime availability, PHP CLI execution, and write permissions under `/var/www`.
 
-```bash
-make run-test TEST_SCRIPT=10_nginx_test.php
-```
+## Deployment
 
-Current tests live in `src/tests/` and cover:
+Deployment uses the host-native tool for the target environment. Mount application code at `/var/www` and publish container port `80` through the platform.
 
-- NGINX HTTP response
-- PHP runtime availability
-- CLI execution
-- write permissions under `/var/www`
+The GitHub release pipeline is declared in `.github/workflows/docker-ops.yml` and delegates Docker publishing to `udx/reusable-workflows`.
 
-## Configuration
+For dependency upgrades, include the changed base image/packages and the local verification result in the PR description.
 
-Primary defaults are in `Makefile.variables`:
+## Worker Config
 
-- `DOCKER_IMAGE`
-- `CONTAINER_NAME`
-- `HOST_PORT` / `CONTAINER_PORT`
-- `VOLUMES`
-- `PHP_VERSION`
+`worker.yaml` follows the base Worker config contract for runtime `config.env` values and `config.secrets` references. Deployment environment variables override values declared in `worker.yaml`.
 
-Container/runtime config files:
+See [docs/worker-config.md](docs/worker-config.md) for the local config reference.
 
-- `etc/configs/nginx/default.conf`
-- `etc/configs/php/php-fpm.conf`
-- `etc/configs/php/www.conf`
-- `etc/configs/worker/services.yaml`
+References:
 
-## Development
+- https://github.com/udx/worker/blob/latest/docs/config.md
+- https://github.com/udx/worker/blob/latest/docs/secrets.md
+- https://github.com/udx/worker/blob/latest/docs/deployment.md
 
-Useful commands:
+## Rabbit CI
 
-```bash
-make help
-make build
-make run
-make log
-make clean
-make test
-```
+Rabbit-facing repo context lives in [`.rabbit/`](.rabbit/). This image repo publishes the `worker-php` Docker image; it does not own tenant-specific Rabbit lifecycle manifests.
+
+See [`.rabbit/README.md`](.rabbit/README.md) for Rabbit CI entry points, delivery notes, and generated repo context handling.
 
 ## Resources
 
 - Docker Hub: https://hub.docker.com/r/usabilitydynamics/udx-worker-php
 - Source: https://github.com/udx/worker-php
 - 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
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Commit your changes
-4. Push to your branch
-5. Open a pull request
-
-Include relevant tests and documentation updates with your changes.
 
 ## License
 
-MIT. See [`LICENSE`](LICENSE).
+MIT. See [LICENSE](LICENSE).