engineering/README.md

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. 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.

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.

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 <PROJECT_NAME>-backend and <PROJECT_NAME>-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.