From 07e3306d4610f533e828a4910356bd7318b44035 Mon Sep 17 00:00:00 2001 From: Derek Roberts Date: Tue, 6 Oct 2026 19:14:24 -0700 Subject: [PATCH 1/2] feat: establish Backstage overlay contract and verification --- OVERLAY.md | 181 +++++++++++++++++++++++++++++++++++++++++ README.md | 2 + backend-java/README.md | 2 +- docker-compose.yml | 2 +- renovate.json | 12 ++- 5 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 OVERLAY.md diff --git a/OVERLAY.md b/OVERLAY.md new file mode 100644 index 00000000..8b9b72df --- /dev/null +++ b/OVERLAY.md @@ -0,0 +1,181 @@ +# Backstage Software Template & Module Overlay Contract + +This document specifies the integration contract for consuming modular backends from `quickstart-openshift-modules` as drop-in overlays onto the canonical [`bcgov/quickstart-openshift`](https://github.com/bcgov/quickstart-openshift) repository scaffold. + +--- + +## 1. Architecture & Overlay Mapping + +In the `quickstart-openshift` ecosystem, repositories are structured with decoupled frontend and backend services: + +```text +quickstart-openshift/ +├── frontend/ # React / Vite frontend +├── backend/ # Application backend service +├── common/ # Common OpenShift deployment manifests +├── migrations/ # Database migrations +└── docker-compose.yml # Local development multi-container orchestration +``` + +Modules in this repository provide alternative, drop-in backend implementations: +* **`backend-java/`**: Quarkus Native (GraalVM) with Java 21 LTS bytecode, embedded Flyway migrations, and sub-second startup. +* **`backend-py/`**: FastAPI with Python 3.14, SQLAlchemy, and automated model generation. + +When a module is selected, its directory maps directly to the root `backend/` directory of the target project: +$$\text{quickstart-openshift-modules/backend-java/} \longrightarrow \text{/backend/}$$ + +--- + +## 2. Backstage Software Template Workflow + +Backstage software templates use built-in actions (`fetch:plain`, `fs:delete`) to scaffold the base repository and stamp the chosen backend module over it. + +### Canonical Backstage Template Definition (`template.yaml`) + +```yaml +apiVersion: backstage.io/v1alpha1 +kind: Template +metadata: + name: quickstart-openshift-quarkus + title: QuickStart OpenShift (Quarkus Java Backend) + description: Scaffold a QuickStart OpenShift application with a Quarkus Native Java backend. +spec: + owner: group:forestry-suite + type: service + parameters: + - title: Project Metadata + required: + - component_id + - owner + properties: + component_id: + title: Service Name + type: string + description: Unique name for your service and OpenShift resources. + owner: + title: Team Owner + type: string + description: GitHub team or group owning the service. + + steps: + # 1. Fetch base quickstart repository scaffold + - id: fetch-base + name: Fetch QuickStart Base Scaffold + action: fetch:plain + input: + url: https://github.com/bcgov/quickstart-openshift/tree/main + targetPath: ./ + + # 2. Purge default Node/NestJS backend implementation + - id: purge-default-backend + name: Remove Default Backend + action: fs:delete + input: + files: + - ./backend + + # 3. Overlay Quarkus Java module into ./backend + - id: overlay-backend-java + name: Overlay Quarkus Java Backend + action: fetch:plain + input: + url: https://github.com/bcgov/quickstart-openshift-modules/tree/main/backend-java + targetPath: ./backend + + # 4. Publish to GitHub + - id: publish + name: Publish Repository + action: publish:github + input: + repoUrl: github.com?owner=${{ parameters.owner }}&repo=${{ parameters.component_id }} + defaultBranch: main +``` + +--- + +## 3. Drop-in File & Interface Contract + +To guarantee zero dangling files and seamless CI/CD pipeline execution in `quickstart-openshift`, each module adheres strictly to the following contract: + +### A. File Taxonomy + +When overlaid into `backend/`, the module provides: +* `Dockerfile`: Container image build instructions. +* `openshift.deploy.yml`: OpenShift deployment template. +* `src/`: Application source code. +* Runtime & build toolchain configuration (`pom.xml`, `.mvn/`, `mvnw` for Java; `pyproject.toml`, `uv.lock` for Python). +* `.dockerignore`: Build artifact exclusion rules. + +### B. Container Image & Build Contract +* **Execution User:** Non-root (`USER 1001`). +* **Port Binding:** Must listen on port `3000` (`EXPOSE 3000`, `PORT=3000`). +* **Container Context:** Builds cleanly from the root of `backend/` (`docker build -f backend/Dockerfile backend/`). + +### C. OpenShift Deployment Template Contract (`openshift.deploy.yml`) +The template must match the parameter conventions consumed by `bcgov/quickstart-openshift/.github/workflows/reusable-deploy.yml`: +* **Parameters:** `NAME`, `COMPONENT` (defaults to `backend`), `ZONE`, `IMAGE_TAG`, `REGISTRY`, `ORG_NAME`, `DOMAIN`, `CPU_REQUEST`, `MEMORY_REQUEST`, `MEMORY_LIMIT`, `LOG_LEVEL`. +* **Database Secret Binding:** Binds credentials from `${NAME}-${ZONE}-database`: + * `database-name` + * `database-user` + * `database-password` +* **Probes:** Configures `startupProbe`, `readinessProbe`, and `livenessProbe` hitting port `3000` (`http`). + +### D. Database Migrations +* **Quarkus Java (`backend-java`)**: Embeds Flyway database migrations inside the application binary. Migrations execute automatically upon application startup under the `java_api` schema. The standalone `migrations` container in `quickstart-openshift` is bypassed or retained for supplementary schemas. +* **FastAPI Python (`backend-py`)**: Includes `backend-py/db/migrations` run via Flyway under `py_api` schema. + +--- + +## 4. Local Development (`docker-compose.yml`) Contract + +To run the overlaid Java backend locally alongside PostgreSQL in a stamped `quickstart-openshift` project, update the `backend:` service in `docker-compose.yml`: + +```yaml + backend: + container_name: backend + working_dir: /project + image: docker.io/library/eclipse-temurin:21-jdk + entrypoint: ./mvnw quarkus:dev -Dquarkus.http.host=0.0.0.0 + volumes: + - "./backend:/project" + healthcheck: + test: timeout 10s bash -c 'true > /dev/tcp/127.0.0.1/3000' + environment: + <<: *postgres-vars + QUARKUS_DATASOURCE_DEVSERVICES_ENABLED: "false" + QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://database:5432/postgres + QUARKUS_DATASOURCE_USERNAME: *POSTGRES_USER + QUARKUS_DATASOURCE_PASSWORD: *POSTGRES_PASSWORD + ports: ["3001:3000"] + depends_on: + database: + condition: service_healthy +``` + +* **Live Reloading:** Code modifications in `./backend/src` reload in real-time via Quarkus dev mode. +* **GraalVM Avoidance:** Local execution uses the Java 21 LTS JVM, eliminating the 5-minute AOT native compilation step during development. + +--- + +## 5. Overlay Verification Procedure + +To verify drop-in compatibility against a target repository: + +```bash +# 1. Clone fresh quickstart-openshift and quickstart-openshift-modules +git clone https://github.com/bcgov/quickstart-openshift.git test-quickstart +git clone https://github.com/bcgov/quickstart-openshift-modules.git test-modules + +# 2. Swap backend directory +rm -rf test-quickstart/backend +cp -r test-modules/backend-java test-quickstart/backend + +# 3. Verify clean directory state (no dangling files) +ls -la test-quickstart/backend + +# 4. Verify native container build +podman build -t test-backend-native test-quickstart/backend + +# 5. Verify local compose configuration +podman compose -f test-quickstart/docker-compose.yml config +``` diff --git a/README.md b/README.md index 45ad4a1d..eaa17f33 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Modular plug-ins for the [QuickStart for OpenShift](https://github.com/bcgov/qui When scaffolding with Backstage or manually swapping backends in `quickstart-openshift`, the chosen module (e.g., `backend-java/`) maps to the `backend/` directory of the target project, providing its source code, Dockerfile, and OpenShift deployment template (`openshift.deploy.yml`). +For full details on the Backstage software template workflow, file compatibility contracts, and the standardized `docker-compose.yml` snippet, consult the [Backstage Overlay Contract](OVERLAY.md). + ## Features * Cloud Native Java with Quarkus and GraalVM native images for minimal resource footprints diff --git a/backend-java/README.md b/backend-java/README.md index 4fefe6d9..13284a85 100644 --- a/backend-java/README.md +++ b/backend-java/README.md @@ -5,7 +5,7 @@ This project uses Quarkus, the Supersonic Subatomic Java Framework. If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ . ### Prerequisites -- [x] Java 17 JDK +- [x] Java 21 JDK - [x] Docker ## Running the application in dev mode diff --git a/docker-compose.yml b/docker-compose.yml index 3e57db00..40e801f1 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -100,7 +100,7 @@ services: backend-java: profiles: ["java", "all"] - image: docker.io/library/eclipse-temurin:27-jdk + image: docker.io/library/eclipse-temurin:21-jdk container_name: backend-java working_dir: /project entrypoint: ./mvnw quarkus:dev -Dquarkus.http.host=0.0.0.0 diff --git a/renovate.json b/renovate.json index 751cbbc9..ca166e95 100644 --- a/renovate.json +++ b/renovate.json @@ -4,5 +4,15 @@ "extends": [ "github>bcgov/renovate-config#2026.9.26" ], - "minimumReleaseAge": "0 days" + "minimumReleaseAge": "0 days", + "packageRules": [ + { + "description": "Lock Eclipse Temurin to Java 21 LTS for backend-java development service", + "matchPackageNames": [ + "eclipse-temurin", + "docker.io/library/eclipse-temurin" + ], + "allowedVersions": "<22" + } + ] } From e943f61605a3cabc1603c61a01402e9fcfec66d1 Mon Sep 17 00:00:00 2001 From: Derek Roberts Date: Tue, 6 Oct 2026 19:23:39 -0700 Subject: [PATCH 2/2] fix(docs): align Backstage template API version and add backend-py dockerignore --- OVERLAY.md | 13 +++++++++---- backend-py/.dockerignore | 14 ++++++++++++++ 2 files changed, 23 insertions(+), 4 deletions(-) create mode 100644 backend-py/.dockerignore diff --git a/OVERLAY.md b/OVERLAY.md index 8b9b72df..e27c3895 100644 --- a/OVERLAY.md +++ b/OVERLAY.md @@ -33,7 +33,7 @@ Backstage software templates use built-in actions (`fetch:plain`, `fs:delete`) t ### Canonical Backstage Template Definition (`template.yaml`) ```yaml -apiVersion: backstage.io/v1alpha1 +apiVersion: scaffolder.backstage.io/v1beta3 kind: Template metadata: name: quickstart-openshift-quarkus @@ -53,9 +53,9 @@ spec: type: string description: Unique name for your service and OpenShift resources. owner: - title: Team Owner + title: GitHub Repository Owner type: string - description: GitHub team or group owning the service. + description: GitHub organization or user account where the repository will be created. steps: # 1. Fetch base quickstart repository scaffold @@ -176,6 +176,11 @@ ls -la test-quickstart/backend # 4. Verify native container build podman build -t test-backend-native test-quickstart/backend -# 5. Verify local compose configuration +# 5. Apply the Java backend Compose definition from Section 4 to test-quickstart/docker-compose.yml +# (Replace the default node backend service block with the Java service snippet) + +# 6. Verify local compose configuration and start services podman compose -f test-quickstart/docker-compose.yml config +podman compose -f test-quickstart/docker-compose.yml up -d backend database +curl -f http://localhost:3001/ ``` diff --git a/backend-py/.dockerignore b/backend-py/.dockerignore new file mode 100644 index 00000000..086f7da4 --- /dev/null +++ b/backend-py/.dockerignore @@ -0,0 +1,14 @@ +.venv/** +__pycache__/** +*.pyc +*.pyo +.pytest_cache/** +.ruff_cache/** +.coverage +test/** +.dockerignore +.gitignore +Dockerfile +*.yml +*.yaml +*.md