Skip to main content

New App

An app is assembled from a Clustercore base + selected modules; its repo is thin. Follow in order. (Architecture: Project Architecture; releasing: Cut a Release.)

1. Create the repo​

CLUSTER-APPS project, workspace clustersco. Name = the product (bgvchecker). Single trunk develop only (no main); protect it. Seed the thin structure:

<app>/
  app-config.yml          # clustercore_repo + clustercore_ref (the exact core tag)
  version.yml             # lockfile: app + core + each module db_version
  modules/                # git submodules, each pinned to a released tag
  assemble.sh             # clones core @ ref, overlays modules, builds the image
  docker-stack.yml        # Swarm deploy (start-first / stop-first)
  .conf.example           # env var contract (never commit real secrets)
  CHANGELOG.md
  bitbucket-pipelines.yml # CI + build-on-tag + promote

2. Pin the core + add modules​

# app-config.yml: clustercore_ref = the exact Clustercore tag
git submodule add git@bitbucket.org:clustersco/bgv_templates.git modules/bgv_templates
git -C modules/bgv_templates checkout 1.4.0     # a released TAG, never a loose commit
git add .gitmodules modules/bgv_templates version.yml && git commit -m "BGV-1 Pin bgv_templates 1.4.0"

Push each module/core tag before this app references it, or CI fails "reference is not a tree".

3. CI/CD + environments​

  • bitbucket-pipelines.yml: on develop → tests + lint; on a SemVer tag → assemble.sh builds and pushes clustersco/<app>:<ver>, then promotes.
  • Bitbucket Deployments environments: Development (auto) → Staging (promote same digest) → Production (promote after a required manual approval). See Build & Deploy.

4. Delivery wiring​

  • Jira App project on the shared schemes (key like BGV); assign it to its Category; create one Scrum board. Compass service entry. Add the repo to the Git → Jira automation. See Governance.

5. First release​

Cut release/1.0.0, set version.yml app version 1.0.0, finalize CHANGELOG.md, PR + merge, tag 1.0.0 on develop, push — the tag builds the image and runs Dev → Staging → Prod. Set the Jira Fix Version. Full runbook: Cut a Release.

Checklist​

  • Repo in CLUSTER-APPS, develop protected, thin structure seeded
  • app-config.yml core ref set · modules submoduled at tags · version.yml complete
  • Pipelines: test + build-on-tag + promote; Dev/Staging/Prod (prod approval)
  • Jira App project + board + Category · Compass entry · Git→Jira automation
  • 1.0.0 tagged and promoted; Fix Version set