Add Collaborator Deployment

Use this checklist when adding a new public OGRRE collaborator deployment.

Use <collaborator> for the short deployment key, such as rrc, ca, isgs, newts, or osage. Use <COLLABORATOR> for the uppercase GitHub secret prefix.

Some existing backend workflow fields are still named DEPLOY_ENV. In this checklist, their value should be the collaborator key unless the existing workflow has a documented exception.

0. Prerequisites

Refer to the Prerequisites section of the Backend on GKE for details of prerequisite permissions/software needed.

1. Choose names

Confirm the names before changing code:

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`

Keep branch names, workflow names, secrets, App Engine service names, and DNS names aligned.

2. Update Terraform

In orphaned-wells-ui-server/deployment/terraform/variables.tf, add the collaborator to the gke_backends default map for a shared, long-lived deployment:

variable "gke_backends" {
# existing type declaration...

default = {
  # existing collaborators...
  "<collaborator>" = {}
}
}

Use terraform.tfvars only for uncommitted local overrides or testing. For example:

gke_backend_overrides = {
"<collaborator>" = {}
}

Default naming creates the backend namespace, upload bucket, GKE static IP, primary DNS record, and test DNS record from the collaborator key. Add optional settings in the same map only when defaults are not enough:

variable "gke_backends" {
# existing type declaration...

default = {
  # existing collaborators...
  "<collaborator>" = {
    # Only set this when the bucket cannot use the default "<collaborator>_uploads" name.
    upload_bucket_name   = "existing-bucket-name"
    replicas             = 2
    cpu_request          = "1"
    memory_request       = "4Gi"
    cpu_limit            = "1"
    memory_limit         = "4Gi"
    persistent_disk_size = "20Gi"
  }
}
}

The default collaborator API target is 2 replicas with 1 CPU and 4 GiB memory per pod. Processing workers retain 1850m CPU and 12 GiB. Use overrides when the collaborator needs different sizing, such as a smaller temporary test deployment.

With ENABLE_TERRAFORM_CI=true, merge the shared configuration changes to main and review the Terraform plan in GitHub. New collaborator resources or outputs require apply approval; an already-current configuration can finish through automatic no-change verification. Required collaborator overrides must be tracked in variables.tf, not left in a local terraform.tfvars file. For the disabled rollout fallback, run Terraform locally:

cd orphaned-wells-ui-server/deployment/terraform
terraform init
terraform workspace select ogrre
terraform plan
terraform apply

If Terraform creates a new upload bucket, grant the storage runtime service account access to that bucket before deploying the backend. If the collaborator will use batch Document AI processing with that bucket as an input or output bucket, grant the Document AI runtime service account the matching batch bucket access too. See Create Google service-account keys.

caution

Adding a name to gke_backends or gke_backend_overrides creates only the GKE backend infrastructure for that collaborator. Only add an entry to legacy_backend_vms and enabled_legacy_backend_vms if you intentionally need Terraform to manage a legacy VM.

3. Update backend deployment targets

Enabled workflows read the new collaborator's target live after apply. Only for the disabled rollout fallback, update the backend repository secret:

terraform workspace select ogrre
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 new collaborator exists in the JSON:

terraform workspace select ogrre
terraform output -json kubernetes_deploy_targets | jq --arg collaborator "<collaborator>" '.[$collaborator]'

4. Add backend runtime secrets

Add a backend repository secret named:

<COLLABORATOR>_ENV

The secret should contain the backend runtime .env content for this collaborator. Set both ENVIRONMENT and COLLABORATOR to the collaborator key unless there is a specific reason for that deployment to differ.

For GKE deployments, the workflow strips and rewrites STORAGE_BUCKET_NAME from the Terraform deployment target. Do not rely on the runtime env secret to override the Terraform upload bucket name.

Update .github/workflows/deploy-k8s-dispatch.yml so it accepts the new collaborator:

Add <collaborator> to workflow_dispatch.inputs.DEPLOY_ENV.options.
Add <COLLABORATOR>_ENV to workflow_call.secrets.
Add <COLLABORATOR>_ENV_CONTENT to the Prepare runtime env file env block.
Add a case branch mapping <collaborator> to <COLLABORATOR>_ENV_CONTENT.

Optionally add a dedicated workflow such as:

.github/workflows/deploy-k8s-<collaborator>.yml

5. Initialize MongoDB

Before the new backend is used, initialize the collaborator database with the required OGRRE roles, first team, and first user.

First create a MongoDB database user for the collaborator, such as ogrre-<collaborator-name>, and grant it the privileges OGRRE needs on the new collaborator database. This must be done by someone with MongoDB privileges. Store this user's credentials as DB_USERNAME and DB_PASSWORD in the backend <COLLABORATOR>_ENV secret.

Use the InitializeMongoDB.py script referenced in Create and connect MongoDB database. Download it directly here: InitializeMongoDB.py. Run it once for the new database:

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 same DB_NAME, DB_USERNAME, DB_PASSWORD, and DB_CONNECTION values that will be stored in the backend <COLLABORATOR>_ENV secret. The database hostname should match the host portion expected by the script, without the mongodb+srv:// prefix.

After initialization, confirm the database contains the required roles, teams, and users collections.

6. Deploy and verify the backend

Run the dedicated workflow or dispatch workflow. Then verify:

gcloud container clusters get-credentials uow-backend-gke --region us-central1 --project <PROJECT_ID>

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
curl -f https://<collaborator>-server.uow-carbon.org/health

7. Add the frontend

In orphaned-wells-ui:

Add deployment/app-engine/app-<collaborator>.yaml.
Add .github/workflows/deploy-<collaborator>.yml.
Add the frontend repository secret <COLLABORATOR>_BACKEND_URL with no trailing slash.
Add <collaborator>.uow-carbon.org/* to deployment/app-engine/dispatch.yaml.
Deploy the frontend workflow.
Deploy dispatch.yaml.

When editing the frontend workflow, set the existing collaborator field to the collaborator key unless an existing deployment has a documented exception.

See Frontend on App Engine for details.

8. Add the App Engine custom domain

In the Google Cloud console, open App Engine -> Settings -> Custom domains. If the console labels this page differently, use Domain mappings.

Add a new custom domain mapping for <collaborator>.uow-carbon.org and associate it with the App Engine frontend service, <collaborator>-uow.

9. Configure frontend DNS and OAuth

Add frontend DNS records for <collaborator>.uow-carbon.org using the same App Engine frontend IPv4 and IPv6 addresses as the other frontend deployments.

Add both frontend URLs to Google OAuth credentials:

The App Engine generated service URL.
https://<collaborator>.uow-carbon.org.

10. Confirm application setup

Confirm the collaborator deployment has:

MongoDB database, collections, indexes, roles, and initial users.
Processor metadata and schemas for the collaborator.
Storage runtime service-account access to the collaborator upload bucket if using STORAGE_BACKEND=google.
Document AI runtime service-account access to the collaborator processors, plus batch input/output bucket access if using DOCUMENT_AI_BACKEND=google.
Deployment service-account access for the backend and frontend deployment workflows, with separate WIF identities for Terraform CI.
Frontend OAuth sign-in and backend authorization working together.

Common pitfalls

enable_gke=true controls only GKE resources; legacy VMs are managed only when listed in enabled_legacy_backend_vms.
Updating DNS is not enough for GKE. The Ingress host and ManagedCertificate domain must match the Terraform deployment target's hostname.
After target changes, approve Terraform apply and redeploy the backend. Refresh K8S_DEPLOY_TARGETS only for the disabled rollout fallback.
Frontend backend URL secrets should not have trailing slashes.
New collaborators must be added to deploy-k8s-dispatch.yml; a dedicated workflow alone is not enough.

0. Prerequisites​

1. Choose names​

2. Update Terraform​

3. Update backend deployment targets​

4. Add backend runtime secrets​

5. Initialize MongoDB​

6. Deploy and verify the backend​

7. Add the frontend​

8. Add the App Engine custom domain​

9. Configure frontend DNS and OAuth​

10. Confirm application setup​

Common pitfalls​