# Engineering Versioned skills, Java standards, formatting, coverage checks, and the Gitea Actions / Maven Java 25 / npm / Docker Compose recipe. Architecture and specifications belong to [landscape](http://192.168.2.28:3000/wanjakrah/landscape). Source attribution is in SOURCE.md; upstream skill licenses accompany each skill. ## Start a project Clone this repository and check out a released tag. Use JDK 25, Maven, Python 3, Git, Docker with Compose, and a supported Node version for a frontend. ```sh python3 create-project.py my-project ../my-project --version v1.0.0 --components both --runner engineering ``` Choose `backend`, `frontend`, or `both`. The command refuses existing destinations and creates local files only. The backend starter is Quarkus; the frontend starter uses npm and a minimal static page. Replace these starters with application code while preserving the configured build commands and container contracts. Initialize the resulting Git repository and commit its generated resources. Create the remote repository separately, configure its runner and secrets, then push. The runner label must match an available **host** runner with the required tools. `--runner` deliberately has no machine-specific default. ## Consumer layout and configuration `engineering.lock.json` selects a repository, immutable semantic version tag and full commit SHA. `scripts/engineering.py` is the independent bootstrap, and `generated/` is the committed release snapshot. No sibling checkout or global skill installation is needed for ordinary use. Regeneration uses Git credentials or a Git credential helper; never place credentials in the lockfile URL. ```sh mvn -N -Pregenerate-engineering validate python3 scripts/engineering.py --check mvn -Dformat.mode=check clean verify java generated/ci/Ci.java verify java generated/ci/Ci.java test java generated/ci/Ci.java release-test ``` The Maven regeneration profile skips formatting and works without `generated/`. CI checks regeneration in a temporary checkout before running the pipeline. Added, removed, modified and executable-bit changes fail the check. Runtime `target/` and Python cache output are not release resources. Updates remove obsolete generated files and never overwrite project-owned files outside `generated/`. `engineering.properties` supplies project defaults; environment variables take precedence. Required settings are `PROJECT_NAME` and at least one of `BACKEND_MODULE` / `FRONTEND_MODULE`. Modules must be relative paths within the project. Image names are `-backend` and `-frontend`; changing PROJECT_NAME configures that namespace without changing shared code. `BACKEND_CONTEXT` defaults to `.`, and `FRONTEND_CONTEXT` to its module path. Both Dockerfiles provide a `prebuilt` target packaging verified output and a default standalone source build. `FORMAT_DIRECTORIES` lists comma-separated handwritten Java directories. Backend verification prepares a standards classpath, runs the shared standards checker and requires 80% line coverage. Application waivers remain in `tooling/standards/waivers.tsv`; no waiver is supplied by default. `FRONTEND_TEST_COMMAND` is a JSON argument array, defaulting to the established Vitest JUnit command; the starter sets `["npm","test"]`. Frontend verification runs npm ci, lint, tests, and build. `BROWSER_TESTS=true` enables the recipe's Playwright/JaCoCo integration for a backend and frontend. Configure `CI_READINESS_URL`, `PLAYWRIGHT_IMAGE`, `CI_DATABASE`, `DATABASE_NAME` and `DATABASE_USER` as appropriate. The browser recipe expects backend port 8080, frontend port 8080, a backend JaCoCo agent and CLI prepared by Maven, and npm's `e2e` script. Projects without that integration leave BROWSER_TESTS=false. ## Gitea setup Build workflows need a host runner, `TARGET_PLATFORM` (for example linux/amd64), and `REGISTRY_USER` / `REGISTRY_TOKEN` secrets with the repository/package access needed for registry publication. The runner must also be able to read the pinned engineering repository during the regeneration check. For private engineering, install a read-only credential helper on the runner. Application registry and release tokens are not used as implicit bootstrap credentials. Publication is restricted to main after verification. Immutable commit images are pulled back and checked before moving main tags. A host lock serializes publication; a newer main prevents an older run from moving those tags. Manual deployment and rollback workflows require variables `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_PORT`, `DEPLOY_DIRECTORY`, `DEPLOY_REGISTRY`, and secrets `RELEASE_TOKEN`, `DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`. Release eligibility requires a successful main-push build.yaml run. Keep build.yaml's filename when adapting the recipe. Configure Gitea access, registry access and SSH host trust explicitly. Runner setup mechanisms are available as `configure-gitea`, `configure-docker` and `install-runner`. Supply GITEA_SERVER_URL, CI_REPOSITORY, RUNNER_LABEL and INSECURE_REGISTRY where applicable; the latter is only for a deliberately trusted internal HTTP registry. Runner configuration and service templates are project files under ci/runner/. Installation currently supports Linux x86_64 host runners. ## Deployment and recovery Projects own deploy/compose.yaml, deploy/health.sh and production.env. Set COMPOSE_PROJECT, DEPENDENCY_SERVICES and REQUIRED_DEPLOY_SECRETS in project configuration. Backend/frontend services use BACKEND_IMAGE / FRONTEND_IMAGE, RELEASE_SHA and RELEASE_VERSION. Missing roles are represented by `-` in release state; at least one image is required. Dependency services are started without recreating their storage. Application containers alone are recreated on releases. The remote mechanism requires a dedicated directory with owner-only production.env containing BIND_IP, FRONTEND_PORT, DOCKER_BIN, DOCKER_CONFIG and DOCKER_SUDO. The bind IP must be private, and the port 1024..65535. Provision a pull-only registry login. `generated/deploy/provision.sh` accepts directory, registry user, registry, bind IP, port and Docker executable. Optional `generated/deploy/enable-docker.sh` takes deployment account and Docker executable and must be run by an administrator after reviewing the Docker permission grant. deploy/health.sh defines `application_health`, returning nonzero until the app is ready. It can use the shared `compose` and `docker_cmd` functions. Health scripts, Compose configuration, digests and deployment settings are retained per release. For pre-S19 retained releases lacking health.sh/settings, the current project health function/settings provide compatibility; verify them before rolling back across this migration. Existing release-state JSON remains compatible. Locking, a pending journal, digest/revision checks, bounded readiness checks and automatic recovery protect replacement. An ambiguous state write or failed recovery retains the journal and lock for manual inspection. Inspect retained state, pending.json, history and diagnostics before repairing a deployment; never blindly delete a lock. Each application must document its own recovery procedure and database-schema rollback limits. Production deployment remains manual. ## Releases and upgrades Release the resources, mechanisms and templates together. Use semantic version tags `vMAJOR.MINOR.PATCH`; never move or reuse a published tag. Breaking changes increase MAJOR. Record required project-file changes in UPGRADING.md before tagging. Consumers update both tag and commit, regenerate, review and commit the diff. The bootstrap rejects a tag resolving to a different commit and never upgrades automatically. Templates create project-owned files once; upgrading only replaces generated/. Bootstrap/profile/workflow changes require deliberate consumer edits. ## Validation Run `python3 -m unittest discover -s tests`. The example definition is examples/recipe-demo.json. Generate it with create-project.py and use the same pipeline as any consumer. `tests/acceptance.py` exercises generated projects and isolated deployment/rollback without touching production. Validation evidence is recorded in VALIDATION.md.