@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/templates/business-service/.gitlab-ci.yml

@@ -0,0 +1,409 @@
+# --- oa-ci v1
+# Written by @onlineapps/conn-orch-validator (row G-CI of
+# manifests/biz-service.manifest.json). The PLATFORM half of this pipeline: which
+# pipelines run at all, how a service is built, how its image is identified (R5),
+# how the digest reaches the deploy (R1/R2), that the installation document and
+# the migrations still agree, the uniform gate that runs before the SSH step
+# (confirmation biz-service-manifest 008) and the post-deploy gate that runs
+# after it (confirmation deploy-gate-targets 003). npx oa-sync-template .gitlab-ci.yml
+# --target . rewrites everything between these two markers and nothing outside
+# them.
+#
+# Outside them is this repository's own: its test job - which database, which
+# ci:gate:* steps and which artefacts its integration needs is a fact about the
+# service - and whatever else it runs. The stages this block declares (test,
+# build, secret-detection, deploy) cover those jobs too; measured over the eight
+# biz repositories on 2026-09-11, none declares a fifth stage.
+include:
+  - template: Jobs/Secret-Detection.gitlab-ci.yml
+
+workflow:
+  name: "$CI_PROJECT_NAME — $CI_COMMIT_BRANCH [$CI_PIPELINE_SOURCE]"
+
+stages:
+  - test
+  - build
+  - secret-detection
+  - deploy
+
+variables:
+  # R5: one commit-sha scheme across the platform — the FULL sha, the way infra
+  # tags. Two lengths would mean two schemes and the release manifest needs one.
+  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+  IMAGE_LATEST: $CI_REGISTRY_IMAGE:latest
+
+verify-installation-contract:
+  stage: test
+  image: alpine:latest
+  script:
+    - sh scripts/verify-installation-docs-sql-contract.sh
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"
+
+build:
+  stage: build
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    # A password on a command line stands in the runner's process table for the
+    # length of the build and in every trace that echoes the command. The deploy
+    # host's own login has read it from stdin since it was written; both ends of
+    # one login now agree.
+    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+    - docker build --target production -t $IMAGE -t $IMAGE_LATEST .
+    - docker push $IMAGE
+    - docker push $IMAGE_LATEST
+    # R1: the deploy target is the digest, and it exists only after the push.
+    - |
+      # --format is not honoured by the buildx on the runner: it prints the whole
+      # descriptor (Name/MediaType/Digest), so the digest would be captured
+      # multi-line and build.env rejected as an invalid dotenv artifact. Parse
+      # the Digest field.
+      BIZ_IMAGE_DIGEST=$(docker buildx imagetools inspect "$IMAGE" | awk '/^Digest:/ { print $2; exit }')
+      if ! printf '%s' "$BIZ_IMAGE_DIGEST" | grep -qE '^sha256:[0-9a-f]{64}$'; then
+        echo "[build] FATAL: no valid digest resolved for $IMAGE - got '$BIZ_IMAGE_DIGEST', expected sha256:<64 hex>. The deploy would have no immutable target. Fix: confirm the push succeeded and that buildx can read $CI_REGISTRY." >&2
+        exit 1
+      fi
+      echo "[build] $IMAGE -> $BIZ_IMAGE_DIGEST"
+      echo "BIZ_IMAGE_DIGEST=$BIZ_IMAGE_DIGEST" > build.env
+  artifacts:
+    reports:
+      dotenv: build.env
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"
+
+secret_detection:
+  stage: secret-detection
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"
+
+deploy-production:
+  stage: deploy
+  # The uniform runs here (confirmation biz-service-manifest 008), so the job
+  # needs the runtime the pinned engine declares — the same major the test stage
+  # and the Dockerfile carry, which is what R3 of the deploy contract compares.
+  image: node:24-alpine
+  variables:
+    # The engine answers the rows that read the platform SSOT only for a service
+    # lying at <root>/api_biz/<service> beside <root>/api. GitLab decides where a
+    # project is checked out, so the job ASKS for the one place that IS that
+    # layout — no symlink (api rule: No Symlinks) and no second copy of this
+    # repository, which would leave two trees and no way to tell which one the
+    # verdict was about. Needs [runners.custom_build_dir] enabled on the runner.
+    GIT_CLONE_PATH: $CI_BUILDS_DIR/oa-uniform/api_biz/__SERVICE_NAME__
+    # Where the platform SSOT is read from, and which state of it a production
+    # deploy is measured against. Read access is granted by the api project's CI
+    # job-token allowlist — the owner's step, outside any repository
+    # (confirmation biz-service-manifest 008 point 2).
+    API_PROJECT_PATH: onlineapps/oadrive/infra-mono
+    API_UNIFORM_REF: production
+    # Which checks judge this deploy. The gate has no default target: the job
+    # declares what it is measured by (confirmation deploy-gate-targets 002),
+    # and the name is the service's registry identity — the one
+    # api/config/services.json carries and the contract files its target under.
+    DEPLOY_GATE_TARGETS: "biz:__REGISTRY_NAME__"
+  before_script:
+    # Preconditions first, before anything is installed or deployed
+    # (automation-gates.md §1 requirement 4). The post-deploy gate reads the
+    # heartbeat projection on the INFRA box as its own read-only account
+    # (confirmation deploy-gate-targets 003 point 3); without that identity this
+    # job could deploy a service and then not verify it, which is exactly the
+    # false guarantee §5 of the same rule names. So it refuses instead, and
+    # there is no branch on which the gate is skipped (§1 requirement 5).
+    - |
+      # gate-identity-check
+      missing=""
+      [ -n "${GATE_INFRA_HOST:-}" ] || missing="$missing GATE_INFRA_HOST"
+      [ -n "${GATE_INFRA_USER:-}" ] || missing="$missing GATE_INFRA_USER"
+      [ -n "${GATE_INFRA_SSH_PRIVATE_KEY:-}" ] || missing="$missing GATE_INFRA_SSH_PRIVATE_KEY"
+      if [ -n "$missing" ]; then
+        echo "[deploy] FATAL: the post-deploy gate has no identity on the infra box - missing CI variable(s):$missing. Expected: the group-level variables GATE_INFRA_HOST, GATE_INFRA_USER and GATE_INFRA_SSH_PRIVATE_KEY (base64 ed25519 private key of the gate-reader account). Fix: set them in GitLab > Group > Settings > CI/CD > Variables, and install the account on the infra box with api/scripts/provision/gate-reader-install.sh (confirmation deploy-gate-targets 003 point 3)." >&2
+        exit 1
+      fi
+      # end gate-identity-check
+    - |
+      # host-key-check
+      # An ssh that accepts whatever key answers on an address hands the deploy
+      # key, the registry password and the gate-reader key to whoever answered.
+      # Both boxes are therefore pinned from a CI variable, and a missing pin
+      # stops the job HERE, before anything is installed and before the first
+      # connection - never a fallback to accepting the unknown
+      # (automation-gates.md §1 requirements 4 and 5, §2).
+      if [ -z "${DEPLOY_HOST_KEY:-}" ]; then
+        echo "[deploy] Missing CI variable - DEPLOY_HOST_KEY is the ssh-keyscan line of the biz box DEPLOY_HOST ($DEPLOY_HOST), which this job deploys to over ssh. Fix: on a machine that already trusts that box run 'ssh-keyscan -t ed25519 $DEPLOY_HOST' and set its whole output line as DEPLOY_HOST_KEY in GitLab > Group > Settings > CI/CD > Variables." >&2
+        exit 1
+      fi
+      if [ -z "${GATE_INFRA_HOST_KEY:-}" ]; then
+        echo "[deploy] Missing CI variable - GATE_INFRA_HOST_KEY is the ssh-keyscan line of the infra box GATE_INFRA_HOST ($GATE_INFRA_HOST), which the post-deploy gate reads the heartbeat projection from. Fix: on a machine that already trusts that box run 'ssh-keyscan -t ed25519 $GATE_INFRA_HOST' and set its whole output line as GATE_INFRA_HOST_KEY in GitLab > Group > Settings > CI/CD > Variables." >&2
+        exit 1
+      fi
+      # end host-key-check
+    # openssh-client and git for the two SSH steps and the api checkout the
+    # uniform reads; bash, jq and curl for the post-deploy gate — it declares
+    # bash>=4 (declare -A), reads the contract with jq and submits a workflow
+    # smoke with curl. No docker: in remote mode every docker call is carried to
+    # the box that holds the fact, over ssh.
+    - apk add --no-cache openssh-client git bash jq curl
+    - mkdir -p ~/.ssh
+    - echo "$SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/deploy_key
+    - chmod 600 ~/.ssh/deploy_key
+    - echo "$GATE_INFRA_SSH_PRIVATE_KEY" | base64 -d > ~/.ssh/gate_infra_key
+    - chmod 600 ~/.ssh/gate_infra_key
+    # The identity of the two boxes, pinned. Written before the config that
+    # demands it, so no ordering makes the demand unsatisfiable.
+    - echo "$DEPLOY_HOST_KEY" > ~/.ssh/known_hosts
+    - echo "$GATE_INFRA_HOST_KEY" >> ~/.ssh/known_hosts
+    - chmod 644 ~/.ssh/known_hosts
+    # Two boxes, two identities, and neither key is ever offered to the other
+    # box: the deploy key opens the biz box, the gate-reader key the infra box.
+    # ssh_config keeps the FIRST value it finds for a keyword, so the host
+    # blocks come before the catch-all and the catch-all carries only the
+    # host-key policy - which is where it belongs rather than on a command line:
+    # the post-deploy gate this job runs at the end (see its invocation below)
+    # opens its own ssh connections inside the script, and takes no ssh flags
+    # from here, so a policy written per-command would cover the deploy step and
+    # leave the gate connecting to anything that answered.
+    - |
+      {
+        echo "Host $DEPLOY_HOST"
+        echo "  IdentityFile ~/.ssh/deploy_key"
+        echo "  IdentitiesOnly yes"
+        echo "Host $GATE_INFRA_HOST"
+        echo "  IdentityFile ~/.ssh/gate_infra_key"
+        echo "  IdentitiesOnly yes"
+        echo "Host *"
+        echo "  StrictHostKeyChecking yes"
+        echo "  UserKnownHostsFile ~/.ssh/known_hosts"
+      } > ~/.ssh/config
+  dependencies:
+    - build
+  script:
+    # The uniform of this checkout, complete, BEFORE anything is deployed
+    # (confirmation biz-service-manifest 006 point 3, refined by 008): deploy is
+    # confirmation, never discovery. One blocking finding, or a run that could
+    # not look everywhere, and nothing reaches the box. There is no flag and no
+    # variable that turns this off (automation-gates.md §1 requirement 5).
+    - npm ci
+    - scripts/verify-deploy-uniform.sh "$CI_PROJECT_DIR" "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/${API_PROJECT_PATH}.git" "$API_UNIFORM_REF"
+    # R1: refuse to deploy without the immutable target the build stage published.
+    - |
+      if [ -z "${BIZ_IMAGE_DIGEST:-}" ]; then
+        echo "[deploy] FATAL: BIZ_IMAGE_DIGEST is empty - the build stage publishes it as a dotenv artifact. Refusing to deploy without an immutable image target." >&2
+        exit 1
+      fi
+    - echo "Deploying $BIZ_IMAGE_DIGEST to $DEPLOY_HOST ($CI_ENVIRONMENT_URL)"
+    # The read-only api clone the uniform step already made beside this checkout.
+    # Derived from CI_PROJECT_DIR rather than spelled out a second time: the
+    # layout is declared once, in GIT_CLONE_PATH, so the two cannot drift apart.
+    # TWO steps read it: the migration runner streamed to the box below, and the
+    # post-deploy gate at the end of this job.
+    - API_CHECKOUT="$(dirname "$(dirname "$CI_PROJECT_DIR")")/api"
+    # WHICH SCHEMA, IF ANY (confirmation db-migrations-first-deploy 001, phase 2).
+    # Read from the one declaration there is - this service's own installation
+    # contract - and read HERE, on the runner: the contract is this repository's,
+    # jq is in this image, and the box is not asked to carry a JSON parser for two
+    # values. A service that declares no `database` block has no schema to
+    # migrate, and the step below says that out loud rather than passing over it
+    # in silence (automation-gates.md 5: a step that checked nothing must never
+    # look like one that checked).
+    - |
+      CONTRACT="$CI_PROJECT_DIR/config/service/integration-contract.json"
+      if [ ! -f "$CONTRACT" ]; then
+        echo "[deploy] FATAL: no installation contract at $CONTRACT - this deploy cannot tell whether the service has a schema to migrate, and guessing is not an option. Fix: commit config/service/integration-contract.json (the uniform manifest requires it of every biz repository)." >&2
+        exit 1
+      fi
+      BIZ_DB_SCHEMA="$(jq -r '.database.schema // empty' "$CONTRACT")"
+      BIZ_DB_MIGRATIONS="$(jq -r '.database.migrations // empty' "$CONTRACT")"
+      if [ -n "$BIZ_DB_SCHEMA" ] && [ -z "$BIZ_DB_MIGRATIONS" ]; then
+        echo "[deploy] FATAL: $CONTRACT declares database.schema ($BIZ_DB_SCHEMA) and no database.migrations - the deploy would not know which files to apply. Fix: declare the glob of the directory that holds them (api/docs/biz/70-contracts/database-contract.md)." >&2
+        exit 1
+      fi
+      if [ -n "$BIZ_DB_MIGRATIONS" ]; then
+        # The runner applies a DIRECTORY and does not descend into it; the
+        # contract declares the glob (migrations/*.sql, migrations/BASELINE/*.sql),
+        # so the directory is its dirname - the same reading the runbook gives it
+        # (api/docs/setup/INSTALL.md, applying a business schema).
+        BIZ_DB_MIGRATIONS="$(dirname "$BIZ_DB_MIGRATIONS")"
+      fi
+    # DEPLOY_PATH / DEPLOY_HOST / DEPLOY_USER are CI variables: the box decides
+    # where its checkout lives, and no path is baked into this file.
+    #
+    # The registry password travels on STDIN and nowhere else. As an argument of
+    # the remote `bash -s` it stood in the deploy host's process table for the
+    # whole deploy, readable by every account on that box, and in this runner's
+    # argv besides. So the stream the remote shell reads is the password's line
+    # first and the script after it: the remote reads that one line, exports it,
+    # and hands the rest of the stream to `bash -s` - ssh's stdin is a socket
+    # there, so `read` consumes exactly the line and no more.
+    #
+    # The shell the remote runs is ASSEMBLED from three parts, in this order: the
+    # password line, the shell options, and then the platform's own MariaDB
+    # migration runner followed by the body below. The runner is carried rather
+    # than copied - it is api/scripts/lib/mariadb-migrations.sh out of the clone
+    # the uniform step made, so the box applies the same shell the runbook applies
+    # by hand in phase 1, and no second implementation of it exists anywhere
+    # (change-discipline.md - One rail per concern). The options are set once, for
+    # the whole assembled stream, which is why they are no longer the first line
+    # of the body.
+    - |
+      {
+        printf '%s\n' "$CI_REGISTRY_PASSWORD"
+        printf '%s\n' "set -euo pipefail"
+        cat "$API_CHECKOUT/scripts/lib/mariadb-migrations.sh"
+        cat
+      } <<'REMOTE' | ssh $DEPLOY_USER@$DEPLOY_HOST "IFS= read -r REGISTRY_PASSWORD; export REGISTRY_PASSWORD; bash -s -- '$DEPLOY_PATH' '$CI_REGISTRY' '$CI_REGISTRY_USER' '$CI_PROJECT_PATH_SLUG' '$BIZ_IMAGE_DIGEST' '$CI_PROJECT_PATH' '$BIZ_DB_SCHEMA' '$BIZ_DB_MIGRATIONS'"
+      DEPLOY_PATH="$1"
+      REGISTRY="$2"
+      REGISTRY_USER="$3"
+      PROJECT_SLUG="$4"
+      export BIZ_IMAGE_DIGEST="$5"
+      PROJECT_PATH="$6"
+      # Empty when the installation contract declares no `database` block - the
+      # only thing that turns the migration step below on or off.
+      DB_SCHEMA="$7"
+      DB_MIGRATIONS_DIR="$8"
+      # This service's own env file on the box, the per-machine half of the two
+      # the compose file names (../shared.env is the host's). It carries the
+      # migration account - the SAME account the service connects as.
+      SERVICE_ENV="config/env-active/__SERVICE_NAME__.env"
+      # The host-level env file of the biz box, one per box and referenced rather
+      # than copied (server-topology 004) - the same path docker-compose.production.yml
+      # names.
+      HOST_ENV="../shared.env"
+      # REGISTRY_PASSWORD arrives in the environment, from the first line of this
+      # script's own stdin. Empty means the runner had no CI_REGISTRY_PASSWORD:
+      # the pull would fail later with an authentication error that names nothing.
+      if [ -z "${REGISTRY_PASSWORD:-}" ]; then
+        echo "[deploy] FATAL: REGISTRY_PASSWORD is empty - it is read from the first line of this script's own stdin, before bash -s. Expected: CI_REGISTRY_PASSWORD set on the runner. Fix: check the job's CI variables; refusing to deploy without a registry login." >&2
+        exit 1
+      fi
+      DOCKER_CONFIG_DIR="$HOME/.docker-ci/${PROJECT_SLUG}"
+
+      # Onboarding a new biz service must not require a step on the server —
+      # owner decision api/docs/governance/confirmations/server-topology.md 004.
+      # The first deploy therefore creates the checkout itself; the deploy user
+      # holds a read key for every biz repository.
+      if [ ! -d "$DEPLOY_PATH/.git" ]; then
+        echo "[deploy] $DEPLOY_PATH holds no checkout - cloning git@gitlab.com:${PROJECT_PATH}.git"
+        git clone "git@gitlab.com:${PROJECT_PATH}.git" "$DEPLOY_PATH"
+      fi
+
+      cd "$DEPLOY_PATH"
+      # R2: reset, never merge. A local modification on the server would turn a
+      # merge into a conflict and abort the deploy halfway.
+      git fetch origin production
+      git reset --hard origin/production
+      mkdir -p "$DOCKER_CONFIG_DIR"
+      echo "$REGISTRY_PASSWORD" | docker --config "$DOCKER_CONFIG_DIR" login -u "$REGISTRY_USER" --password-stdin "$REGISTRY"
+      echo "[deploy] pulling $BIZ_IMAGE_DIGEST"
+      docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml pull
+
+      # ─── Migrations: after the pull, before the switch ───────────────
+      # Owner decision api/docs/governance/confirmations/db-migrations-first-deploy.md
+      # 001, phase 2. The ordering IS the safety: at this point the new image is
+      # on the box and the OLD container is still serving, so a migration that
+      # fails stops the deploy with the previous version running and the new one
+      # never started. Applying after the switch would mean the new code meets a
+      # schema it does not have; applying before the pull would mean a schema
+      # change for an image that might not even be pullable.
+      #
+      # The account is the SERVICE's, never root: its grants cover its own schema
+      # and nothing else, so a migration that reaches sideways into a neighbouring
+      # database is refused by the server rather than politely applied
+      # (db-accounts-per-service 001). This step CREATES NOTHING - schema and
+      # account are an operator's step in the runbook, phase 1, and a deploy that
+      # provisioned what it found missing would both grant itself those privileges
+      # and hide a wrongly provisioned box.
+      if [ -z "$DB_SCHEMA" ]; then
+        echo "[deploy] migrations NOT APPLICABLE (no database block) - config/service/integration-contract.json declares no database, so this service has no schema to migrate."
+      else
+        # The two env files the compose names, in the order it names them: the
+        # host-level one first, this service's own second, so the same value wins
+        # here that wins inside the container. Reading only one of them would
+        # make this step disagree with the service it migrates for, depending on
+        # which file the box happens to carry DB_HOST in.
+        for env_file in "$HOST_ENV" "$SERVICE_ENV"; do
+          if [ ! -f "$env_file" ]; then
+            echo "[deploy] Missing env file - $env_file does not exist on this box, and docker-compose.production.yml names it: between the two of them they carry the endpoint and the migration account of $DB_SCHEMA. Fix: place it on the box (both are per-machine and never committed), then re-run this deploy." >&2
+            exit 1
+          fi
+          set -a
+          . "$env_file"
+          set +a
+        done
+        missing=""
+        [ -n "${MARIADB_MIGRATION_USER:-}" ] || missing="$missing MARIADB_MIGRATION_USER"
+        [ -n "${MARIADB_MIGRATION_PASSWORD:-}" ] || missing="$missing MARIADB_MIGRATION_PASSWORD"
+        [ -n "${DB_HOST:-}" ] || missing="$missing DB_HOST"
+        [ -n "${DB_PORT:-}" ] || missing="$missing DB_PORT"
+        if [ -n "$missing" ]; then
+          echo "[deploy] Missing environment variable -$missing in $DEPLOY_PATH/$SERVICE_ENV. Expected: the migration account of $DB_SCHEMA (the same account as DB_USER, granted on that schema only) and the endpoint it is reached at. Fix: add the keys to that file on this box; config/env-templates/ declares each of them with the reason it exists." >&2
+          exit 1
+        fi
+        # The precondition confirmation 001 demands before any migration: the
+        # account opens the schema, or this deploy stops and names the runbook.
+        if ! mariadb_migrations_can_open_over_tcp "$DB_HOST" "$DB_PORT" "$DB_SCHEMA"; then
+          echo "[deploy] Schema or account missing - '$MARIADB_MIGRATION_USER' cannot open '$DB_SCHEMA' at $DB_HOST:$DB_PORT. Expected: the schema and the account, with grants on ${DB_SCHEMA}.* and nothing else, provisioned once by an operator. Fix: run the business-schema step of api/docs/setup/INSTALL.md on the infra box, then re-run this deploy. This step never creates either: provisioning is a decision, not a deploy side effect." >&2
+          exit 1
+        fi
+        # The tracker is the caller's state and it lives in the checkout on this
+        # box, under the gitignored config/runtime/ - same file name and same flat
+        # format the runbook writes in phase 1, so a schema already carried
+        # forward is skipped rather than applied twice (confirmation 001:
+        # "fáze 2 nesmí změnit sémantiku trackeru").
+        mkdir -p config/runtime
+        TRACKER="config/runtime/applied-migrations-${DB_SCHEMA}.txt"
+        touch "$TRACKER"
+        apply_mariadb_migrations_over_tcp "$DB_MIGRATIONS_DIR" "$TRACKER" "$DB_HOST" "$DB_PORT" "$DB_SCHEMA"
+        # The runner logs each file it applies; what this line adds is the state
+        # that outlives the deploy. The runner's own counter of files it passed
+        # over is deliberately not echoed: no word that reads as a bypass belongs
+        # anywhere in a deploy job, and the gate that keeps this job free of one
+        # judges by the word, not by the intent.
+        echo "[deploy] migrations $DB_SCHEMA: $MARIADB_MIGRATIONS_APPLIED applied now, $(wc -l < "$TRACKER" | tr -d " ") recorded in $DEPLOY_PATH/$TRACKER"
+      fi
+
+      docker --config "$DOCKER_CONFIG_DIR" compose -f docker-compose.production.yml up -d
+      REMOTE
+    # The deploy is not finished until the platform's own post-deploy gate says
+    # the service is alive: the heartbeat projection is present, UP and fresh,
+    # and the container's RestartCount has not moved over the window
+    # (confirmations deploy-gate-targets 003, deploy-gate-restart-count 001).
+    # The two facts sit on two boxes and this runner is a third, so the gate
+    # runs in remote mode — same script, same contract, same verdicts as a local
+    # run, only reading over ssh.
+    - |
+      # The gate runs out of the same read-only api clone the migration runner
+      # was streamed from; API_CHECKOUT is derived once, above.
+      bash "$API_CHECKOUT/scripts/run-post-deploy-gate.sh" \
+        --target "$DEPLOY_GATE_TARGETS" \
+        --biz-host "$DEPLOY_USER@$DEPLOY_HOST" \
+        --infra-host "$GATE_INFRA_USER@$GATE_INFRA_HOST" \
+        --contract "$API_CHECKOUT/config/deploy-smoke-contract.json"
+  environment:
+    name: production
+    url: https://api.onlineapps.cz
+  rules:
+    - if: $CI_COMMIT_BRANCH == "production"
+# --- end oa-ci v1
+
+test:
+  stage: test
+  image: node:24-alpine
+  variables:
+    RABBITMQ_URL: "amqp://localhost:5672"
+    REGISTRY_URL: "http://localhost:33100"
+    NODE_ENV: "test"
+  script:
+    - npm ci
+    - npm run test:ci
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "production"

package/templates/business-service/Dockerfile

@@ -0,0 +1,27 @@
+# === Production stage (build with: --target production) ===
+FROM node:24-alpine AS production
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+# The manifest conformance check, inside the image that would be deployed
+# (confirmation biz-service-manifest 001 §3.1: "The same check runs in the
+# Dockerfile production stage, so an image with a finding is never built").
+#
+# It is the CLI of @onlineapps/conn-orch-validator, which every service declares
+# under `dependencies` — measured across all eight biz repositories on
+# 2026-09-09 — so `npm ci --omit=dev` above installs it and this line needs
+# nothing the image does not already carry.
+#
+# The rows that read a platform file (the template, api/config/shared-env.json,
+# api/.nvmrc) report NOT RUN here and say so by name: an image has no workspace
+# above it. What runs is every row the repository itself answers, and one
+# finding of severity boot or deploy exits non-zero and fails the build.
+RUN node node_modules/@onlineapps/conn-orch-validator/src/cli/oa-validate.js .
+CMD ["node", "index.js"]
+
+# === Development stage (default) ===
+FROM node:24-alpine
+WORKDIR /app
+COPY package*.json ./
+CMD ["npm", "start"]

package/templates/business-service/README.md

@@ -0,0 +1,213 @@
+<!-- BEGIN GENERATED: biz-service-uniform — regenerate: npx oa-sync-template readme-uniform --target . -->
+Uniform: [biz-service](./node_modules/@onlineapps/conn-orch-validator/manifests/biz-service.manifest.json)
+
+Every `api_biz/*/package.json` that `api/config/services.json` lists wears it (`U-ORPHAN`, `U-IDENTITY`).
+
+Duty sections that apply:
+
+- `files`: F-INIT, F-JEST, F-RUNNER, F-GITIGNORE, F-DOCKERIGNORE, G-PROD, G-CI, G-PROD-IMAGE, G-README, G-SETUP, G-SETUP-INSTALL, G-SETUP-MATRIX, G-SETUP-VALIDATION, X-IGNORED, X-HOOKS, X-PREVAL, X-DB-CONFIG
+- `scripts`: S-TEST, S-ALL-C, S-INT-C, S-COOKBOOKS, S-HOST, S-HOOKS
+- `tooling`: S-SCRIPTS
+- `config`: C-IDENTITY, C-SERVICE, C-OPS, C-CONTRACT, C-CONNECTORS, C-SERVICE-DEAD, C-ENV, G-SHARED-ENV, C-ENV-READS
+- `runtime`: R-NODE, R-MEM, R-PID1, R-PORTS-DEV, R-PORTS
+- `db`: D-DB-CONSISTENT, D-DB-COLLATION, D-DB-PACKAGE, D-DB-NAMING, D-DB-README, D-DB-ACCOUNT, D-DB-HEADERS
+- `docs`: C-LINT, D-PORT, D-NPM, D-SCRIPT, D-RETIRED, D-HEADER, D-LINT
+
+Paths a duty owns:
+
+- `.dockerignore`: F-DOCKERIGNORE (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/gitignore`)
+- `.gitignore`: F-GITIGNORE (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/gitignore`)
+- `.gitlab-ci.yml`: G-CI (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/.gitlab-ci.yml`)
+- `README.md`: G-README (from `./node_modules/@onlineapps/conn-orch-validator/manifests/biz-service.manifest.json`)
+- `config/biz-docs-lint.tree.json`: C-LINT
+- `config/env-templates`: C-ENV, D-DB-ACCOUNT
+- `config/env-templates/shared.env`: G-SHARED-ENV (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/config/env-templates/shared.env`)
+- `config/service/config.json`: C-SERVICE
+- `config/service/integration-contract.json`: C-CONTRACT, D-DB-COLLATION
+- `config/service/operations.json`: C-OPS
+- `docker-compose.production.yml`: G-PROD (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docker-compose.production.yml`), G-PROD-IMAGE, R-PORTS
+- `docker-compose.yml`: F-RUNNER (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docker-compose.yml`), C-IDENTITY, R-MEM, R-PID1, R-PORTS-DEV
+- `docs/80-setup/`: G-SETUP
+- `docs/80-setup/INSTALL.md`: G-SETUP-INSTALL (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docs/80-setup/INSTALL.md`)
+- `docs/80-setup/PLATFORM_MATRIX.md`: G-SETUP-MATRIX (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docs/80-setup/PLATFORM_MATRIX.md`)
+- `docs/80-setup/VALIDATION.md`: G-SETUP-VALIDATION (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/docs/80-setup/VALIDATION.md`)
+- `hooks/pre-commit`: X-HOOKS
+- `init.sh`: F-INIT (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/init.sh`)
+- `jest.config.js`: F-JEST (from `./node_modules/@onlineapps/conn-orch-validator/templates/business-service/jest.config.js`)
+- `migrations/`: D-DB-PACKAGE, D-DB-NAMING, D-DB-HEADERS
+- `migrations/README.md`: D-DB-README
+- `scripts/`: S-SCRIPTS
+- `scripts/run-pre-validation.js`: X-PREVAL
+- `src/config/database.js`: X-DB-CONFIG
+<!-- END GENERATED: biz-service-uniform -->
+
+# __SERVICE_NAME__
+
+__SERVICE_DESCRIPTION__
+
+## Quick Start
+
+```bash
+# 1. Copy env templates
+cp config/env-templates/shared.env config/env-active/shared.env
+cp config/env-templates/service.env config/env-active/__SERVICE_NAME__.env
+
+# 2. Edit config/env-active/ files with actual values
+
+# 3. Start (dev)
+docker compose up -d --build
+
+# 4. Start (production) — the image is pinned by digest, so it is PULLED, never
+#    built here: `docker build` refuses a tag that carries a digest. CI publishes
+#    the value; a manual run has to name the digest it wants.
+BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml pull
+BIZ_IMAGE_DIGEST=sha256:… docker compose -f docker-compose.production.yml up -d
+```
+
+On the production biz box the second env file the compose references is
+`../shared.env` — ONE host-level file per box, at
+`/var/www/html/oadrive/api_biz/shared.env`. It is rendered on the infra box by
+`api/scripts/provision/render-biz-shared-env.sh` and carried over by the
+operator; this compose references it and never copies it (owner decision
+`api/docs/governance/confirmations/server-topology.md` 004 and 005).
+The network there is the external `biz_network`, also created by role-biz. The
+dev arrangement above is a single host and keeps its own
+`config/env-active/shared.env`.
+
+## Structure
+
+```
+config/
+├── service/          # Service metadata (config.json, operations.json)
+├── env-templates/    # Versioned env templates
+└── env-active/       # Runtime env (gitignored)
+src/
+└── handlers/v3/      # One module per operation; the handler: field points here
+tests/
+├── unit/
+└── cookbooks/        # Tier-1 cookbooks, one per operation
+index.js              # Entry point (bootstrap)
+```
+
+There is **no** `src/app.js`, **no** `src/routes/` and no HTTP framework in
+`package.json`: a biz container binds no port, and an operation is reached
+through the `handler:` field in `operations.json` — ADR 0005,
+`api/docs/biz/80-decisions/0005-no-http-in-biz-containers.md`, with the testable
+form of it in `api/docs/biz/00-model/service-shape.md` § No-HTTP tests. Business
+logic goes into `src/handlers/v3/`, the layout `api_biz/hello-service/src/` uses
+— see `api/docs/biz/60-templates/service-template.md` § Expected Structure.
+(Paths are relative to the workspace root, because this README is copied into a
+sibling repository where a link relative to `api/` would not resolve.)
+
+## The example operation
+
+The template ships one working operation, `echo`, so a new service starts from a
+shape that already passes. Three files describe it, and replacing the operation
+means replacing all three together:
+
+| File | States |
+|---|---|
+| `config/service/operations.json` | the contract — `handler`, `bundle_scope`, `mutates`, `input`/`output` schemas |
+| `src/handlers/v3/echo.js` | the behaviour — `echo(input, ctx)`, returning a value |
+| `tests/cookbooks/echo.json` | the Tier-1 assertion — calls the operation and asserts the output BY VALUE |
+
+`echo` is deliberately total and deterministic, which is what lets the cookbook
+assert `length` equals `8` instead of merely asserting that something came back.
+Keep that property when you replace it: a cookbook that asserts only truthiness
+proves the dispatch worked and nothing about the result
+(`.claude/rules/architecture-principles.md` §10a).
+
+## Testing
+
+Suites run **in a container**, in the one-shot test runner this service ships
+beside itself (`__CONTAINER_NAME___tests` in `docker-compose.yml`). It has its
+own memory budget, so a heavy suite can no longer be killed together with the
+service, and the `test` profile keeps it out of a plain `docker compose up`.
+
+```bash
+npm run test:container       # unit suite, in the runner
+npm run test:all:container   # everything test:all chains, in the runner
+```
+
+Each wraps one command — `docker compose run --rm __CONTAINER_NAME___tests npm run <suite>`.
+
+**Rebuilding the runner takes the profile with it.** `profiles: [test]` keeps the
+runner out of a plain `docker compose up`, and out of a plain build for the same
+reason — measured 2026-09-14: `docker compose build --dry-run` builds one image,
+`docker compose --profile test build --dry-run` builds two. So after a change to
+the `Dockerfile` or to the dependencies:
+
+```bash
+docker compose --profile test build
+```
+
+Without it the next `npm run test:container` runs the image the runner was last
+built from, and a suite then passes or fails on code that is no longer in this
+repository — a green run that says nothing about what is committed.
+
+`npm test` and `npm run test:unit` are what runs INSIDE that container; the
+runner is the one rail a suite runs on (owner decision
+`api/docs/governance/confirmations/biz-test-container.md` 001, and manifest rows
+`S-ALL-C` and `S-HOST`). Running them on the host is not a second, quicker way
+to the same answer: the host has neither the service's `env_file` nor its
+network, so what fails there says nothing about the service — which is why no
+`test:host` script exists and why the uniform forbids one.
+
+### Cookbooks (Tier-1)
+
+```bash
+npm run test:cookbooks:container   # in the runner, which has the env
+```
+
+It wraps `npm run test:cookbooks`, the library command
+(`oa-biz-ci-gate run-prevalidation`, manifest row `S-COOKBOOKS`), which is what
+runs inside the container. The cookbook run dispatches real handlers under the
+testing namespace, so it reads `TESTING_TENANT_ID` and `TESTING_WORKSPACE_ID`;
+the runner has both from `env_file`, and the run fails by name if they are
+missing. It writes `conn-runtime/validation-proof.json` — generated,
+gitignored, and **not** what the platform trusts: the proof that counts is the
+one ServiceWrapper writes on every boot
+(`api/docs/biz/50-lifecycle/validation-responsibilities.md` § Data Flow).
+
+This template ships **no** `tests/integration/`, and no script declaring one:
+there is no behaviour here to exercise, and a declaration with nothing behind it
+is the defect `.claude/rules/change-discipline.md` § "Removing something removes
+its declaration" describes. Add the directory together with the first real
+integration test — `.claude/rules/architecture-principles.md` §10a requires one
+for every behavioural change, so the first handler brings its own.
+
+## Contract gates
+
+A fresh scaffold passes `biz-ci-gate verify-contract` — deploy, installation,
+env, test coverage and the library pins — with nothing added by hand:
+
+```bash
+node node_modules/@onlineapps/conn-orch-validator/src/cli/biz-ci-gate.js verify-contract
+```
+
+Two files are what makes that true, and both are copied and substituted with the
+rest of the template: `config/service/integration-contract.json` (the connectors,
+the integration minimum, and — once a handler reads one — the `env` block), and
+`docs/80-setup/{INSTALL,PLATFORM_MATRIX,VALIDATION}.md`, the three installation
+documents the contract requires of every repository
+(`api/docs/standards/repository-installation-sql-contract.md`).
+
+## Memory limits
+
+Two numbers, and they measure different things — the platform norm, recorded in
+`api/docs/governance/confirmations/biz-memory-limits.md` 001:
+
+| Where | Key | Value | Covers |
+|---|---|---|---|
+| service, dev **and** production | `deploy.resources.limits.memory` | `512M` | the resident service process, nothing else |
+| test runner, dev/CI only | `mem_limit` | `1g` | one suite at a time (`--maxWorkers=1`) |
+
+They are prescribed values, not figures derived for this service. The split is
+the point: while one budget covered both, a test run was killed by the kernel
+and took the service down with it — so raising the service limit is never the
+fix for a suite that runs out of memory, and no suite may share the service's
+cgroup.
+
+Revise the service limit when this service exceeds 60% of it in operation,
+measured the way the norm was: cgroup `memory.stat:anon`, sampled inside the
+running container.