Add Collaborator Deployment
Use this checklist when adding a new public OGRRE collaborator deployment using the standard GitHub Actions workflow and default settings.
Enter the short lowercase collaborator key below (such as isgs, newts, osage, or rrc) to populate all commands and resource names on this page.
0. Prerequisites
- Local CLI tools:
gh,gcloud,jq, andpython. - Access to the target GCP project, MongoDB cluster, and GitHub repository settings (
CATALOG-Historic-Records). - See Backend on GKE — Prerequisites for full GCP API and service-account permission details.
1. Choose Collaborator Key
| Item | Pattern |
|---|---|
| Collaborator key | |
| Backend namespace | uow-<collaborator> |
| Backend primary host | <collaborator>-server.uow-carbon.org |
| Backend test host | <collaborator>-k8s-server.uow-carbon.org |
| GKE static IP name | <collaborator>-uow-gke-ip |
| Upload bucket | <collaborator>_uploads |
| Frontend host | <collaborator>.uow-carbon.org |
| App Engine service | <collaborator>-uow |
2. Initialize MongoDB
- Create a MongoDB database and user for the collaborator (e.g.,
ogrre-<collaborator>), granting it read/write privileges on the new database. - Download InitializeMongoDB.py (see Create and connect MongoDB database) and run it once to seed the required
roles,teams, and initial adminuserscollections:
python InitializeMongoDB.py \
--team_name "<team name>" \
--email "<initial-admin-email>" \
--database_username "<DB_USERNAME>" \
--database_password "<DB_PASSWORD>" \
--database_hostname "<DB_CONNECTION>" \
--database_name "<DB_NAME>"
Use the host portion of the connection string (without the mongodb+srv:// prefix) for --database_hostname. Save these DB_NAME, DB_USERNAME, DB_PASSWORD, and DB_CONNECTION values for the backend RUNTIME_ENV secret in the next step.
3. Configure and Deploy the Backend (orphaned-wells-ui-server)
-
Add the collaborator to
terraform.tfvarsand sync to CI: Pull the sharedterraform.tfvarsconfiguration from GCS:./deployment/terraform/scripts/sync_tfvars.sh pullAdd
<collaborator>undergke_backendsindeployment/terraform/terraform.tfvars:gke_backends = {# existing collaborators..."<collaborator>" = {}}Upload the updated file to GCS and sync the
PROD_TERRAFORM_TFVARSGitHub secret:./deployment/terraform/scripts/sync_tfvars.sh push --secret -
Create the GitHub Environment and
RUNTIME_ENVsecret: Prepare a local<collaborator>.envfile with the required runtime settings (the GKE deployment workflow automatically setsENVIRONMENT,BACKEND_URL,STORAGE_BUCKET_NAME, service-account key paths, and worker sizing):COLLABORATOR=<collaborator>ALLOWED_ORIGINS=https://<collaborator>.uow-carbon.orgDB_NAME=<DB_NAME>DB_CONNECTION=<DB_CONNECTION>DB_USERNAME=<DB_USERNAME>DB_PASSWORD=<DB_PASSWORD>REQUIRE_AUTH=trueAUTH_PROVIDER=googletoken_uri=https://oauth2.googleapis.com/tokenclient_id=<GOOGLE_OAUTH_CLIENT_ID>client_secret=<GOOGLE_OAUTH_CLIENT_SECRET>SESSION_COOKIE_DOMAIN=.uow-carbon.orgSESSION_COOKIE_SECURE=trueSESSION_COOKIE_SAMESITE=laxPROJECT_ID=tidy-outlet-412020LOCATION=usSTORAGE_BACKEND=googleDOCUMENT_AI_BACKEND=googleUSE_DB_SCHEMAS=trueBecause Google Cloud Console masks
client_secretafter creation and GitHub Actions secrets are write-only, you can copy the sharedclient_idandclient_secretfrom another local.envfile or read them from an existing GKE namespace such asuow-staging(see Inspecting Kubernetes resources withkubectlfor one-timekubectlcluster authentication):kubectl -n uow-staging get secret backend-runtime-env -o json | \jq -r '.data | "client_id=\(.client_id | @base64d)\nclient_secret=\(.client_secret | @base64d)"'Create the
<collaborator>GitHub Environment and upload the.envfile asRUNTIME_ENV:gh api --method PUT repos/CATALOG-Historic-Records/orphaned-wells-ui-server/environments/<collaborator>gh secret set RUNTIME_ENV \-R CATALOG-Historic-Records/orphaned-wells-ui-server \--env <collaborator> < path/to/<collaborator>.env -
Register the collaborator in
collaborators.json: Add<collaborator>tocollaborators.jsonat the root oforphaned-wells-ui-server:["osage","newts","isgs","rrc","<collaborator>"] -
Merge to
mainand approve Terraform in GitHub Actions: Commit thecollaborators.jsonupdate and merge it tomain. Merging tomaintriggers the Deploy Staging Server to GKE workflow, which generates a Terraform plan for the new collaborator's bucket, namespace, static IP, and DNS records:- In GitHub Actions (
CATALOG-Historic-Records/orphaned-wells-ui-server), open the Deploy Staging Server to GKE run. - Review the Terraform plan summary on the workflow run page.
- If everything looks correct, click Review deployments →
terraform-apply→ Approve and deploy and wait for the infrastructure apply job to finish before proceeding. (Note: Theterraform-applyGitHub Environment is restricted to required reviewers; if you do not have permission to approve it, ask a repository owner to review and approve the plan.)
- In GitHub Actions (
-
Create and push the collaborator branch: Create the
<collaborator>branch frommainand push it to trigger.github/workflows/deploy-k8s-collaborator.yml:git checkout main && git pullgit checkout -b <collaborator> && git push -u origin <collaborator>Once the workflow finishes and the Google-managed TLS certificate activates, verify the health endpoint:
curl -f https://<collaborator>-server.uow-carbon.org/health
4. Configure and Deploy the Frontend (orphaned-wells-ui)
-
Create the GitHub Environment and
BACKEND_URLsecret: ConfigureBACKEND_URL(with no trailing slash) in the<collaborator>GitHub Environment:gh api --method PUT repos/CATALOG-Historic-Records/orphaned-wells-ui/environments/<collaborator>gh secret set BACKEND_URL \-R CATALOG-Historic-Records/orphaned-wells-ui \--env <collaborator> \--body "https://<collaborator>-server.uow-carbon.org" -
Update
collaborators.jsonanddispatch.yaml: Add<collaborator>tocollaborators.jsonat the root oforphaned-wells-ui:["isgs","newts","osage","rrc","<collaborator>"]Add the route for
<collaborator>.uow-carbon.org/*todeployment/app-engine/dispatch.yaml:- url: "<collaborator>.uow-carbon.org/*"service: <collaborator>-uowMerge both changes to
main. -
Create and push the collaborator branch: Create the
<collaborator>branch frommainand push it to trigger.github/workflows/deploy-collaborator.yml:git checkout main && git pullgit checkout -b <collaborator> && git push -u origin <collaborator>The workflow automatically renders
service:<collaborator>-uowusingdeployment/app-engine/app.yaml, builds the React bundle, and deploys the App Engine service.
5. Complete GCP Routing, DNS, and OAuth
After the frontend App Engine service is deployed, complete these one-time GCP configuration steps:
- Deploy
dispatch.yaml:cd orphaned-wells-ui/deployment/app-enginegcloud app deploy dispatch.yaml - Add Frontend Cloud DNS Records:
In Google Cloud DNS, add
A(IPv4) andAAAA(IPv6) records for<collaborator>.uow-carbon.orgusing the same App Engine addresses as the existing frontend instances. - Add the App Engine Custom Domain:
In the Google Cloud Console, open App Engine → Settings → Custom domains (or Domain mappings) and map
<collaborator>.uow-carbon.orgto the<collaborator>-uowservice. - Update Google OAuth Credentials:
In APIs & Services → Credentials, add both frontend URLs to the OAuth client's Authorized JavaScript Origins and Authorized Redirect URIs:
-
https://<collaborator>.uow-carbon.org
-
Optional Customizations and Manual Fallbacks
Custom Terraform resource sizing or bucket names
By default, a collaborator backend uses <collaborator>_uploads for its GCS bucket, 2 API replicas at 1 CPU / 4 GiB memory per pod, and 1850m CPU / 12 GiB memory for batch-processing workers.
To customize these settings (for example, to reuse an existing bucket name or reduce sizing for a smaller test instance), specify optional attributes in gke_backends inside terraform.tfvars:
gke_backends = {
# existing collaborators...
"<collaborator>" = {
upload_bucket_name = "existing-bucket-name"
replicas = 2
cpu_request = "1"
memory_request = "4Gi"
cpu_limit = "1"
memory_limit = "4Gi"
persistent_disk_size = "20Gi"
}
}
For GKE deployments, the workflow overwrites ENVIRONMENT, BACKEND_URL, and STORAGE_BUCKET_NAME from the Terraform deployment target; always configure custom bucket names in terraform.tfvars rather than RUNTIME_ENV.
GCS bucket IAM and external batch buckets
Because ogrre-storage-runtime and ogrre-document-ai have project-level roles/storage.objectUser (and ogrre-document-ai has project-level Document AI roles), newly created <collaborator>_uploads buckets and any arbitrary buckets in the same GCP project inherit access automatically. You only need to grant roles/storage.objectUser manually if a collaborator runs GCS batch uploads from an external bucket in a different GCP project.
Manual dispatch dropdown in deploy-k8s-dispatch.yml
.github/workflows/deploy-k8s-collaborator.yml supports workflow_dispatch on any collaborator branch listed in collaborators.json without editing workflow files. If you also want <collaborator> to appear in the DEPLOY_ENV choice dropdown when manually triggering .github/workflows/deploy-k8s-dispatch.yml from the GitHub Actions UI, add <collaborator> to workflow_dispatch.inputs.DEPLOY_ENV.options in .github/workflows/deploy-k8s-dispatch.yml.
Inspecting Kubernetes resources with kubectl
To run kubectl commands against the GKE cluster (see Backend on GKE — Check rollout status), install the GKE auth plugin and fetch cluster credentials once using a Google account with GKE access in GCP IAM (such as OGRRE_Dev, roles/container.developer, or roles/container.admin):
gcloud auth login
gcloud components install gke-gcloud-auth-plugin
gcloud container clusters get-credentials uow-backend-gke --region us-central1 --project tidy-outlet-412020
kubectl -n uow-<collaborator> get deployment backend
kubectl -n uow-<collaborator> get pods -l app.kubernetes.io/name=orphaned-wells-ui-server -o wide
kubectl -n uow-<collaborator> get managedcertificate backend-cert
Manual Terraform fallback (only when ENABLE_TERRAFORM_CI is disabled)
With ENABLE_TERRAFORM_CI=true, Terraform planning, applying, and reading kubernetes_deploy_targets happen automatically in GitHub Actions. Only use the local commands below when Terraform CI automation is disabled:
cd orphaned-wells-ui-server/deployment/terraform
terraform init
terraform workspace select ogrre
terraform plan
terraform apply
gh auth login
gh secret set K8S_DEPLOY_TARGETS \
--repo CATALOG-Historic-Records/orphaned-wells-ui-server \
--body "$(terraform output -json kubernetes_deploy_targets | jq -c .)"
Confirm the collaborator target exists in the output:
terraform workspace select ogrre
terraform output -json kubernetes_deploy_targets | jq --arg collaborator "<collaborator>" '.[$collaborator]'
Common pitfalls
- DNS vs. Ingress host: Updating DNS alone is not enough for GKE; the Kubernetes Ingress
hostandManagedCertificatedomain are rendered from the Terraform target and require a backend deployment after Terraform apply. - No trailing slashes: Frontend
BACKEND_URLsecrets and OAuth origin entries should not have trailing slashes. - Keep both
collaborators.jsonfiles updated: Ensure<collaborator>is added tocollaborators.jsonin bothorphaned-wells-ui-serverandorphaned-wells-uiso push deployments andmain →<collaborator>sync PRs are active across both repositories.