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             = 1
    memory_request       = "8Gi"
    memory_limit         = "8Gi"
    persistent_disk_size = "20Gi"
  }
}
}

Run Terraform:

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

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

Export the target map and update the backend repository secret. The gh command requires a GitHub account with permission to edit repository Actions secrets:

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 K8S_DEPLOY_TARGETS. 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:

1. Add deployment/app-engine/app-<collaborator>.yaml.
2. Add .github/workflows/deploy-<collaborator>.yml.
3. Add the frontend repository secret <COLLABORATOR>_BACKEND_URL with no trailing slash.
4. Add <collaborator>.uow-carbon.org/* to deployment/app-engine/dispatch.yaml.
5. Deploy the frontend workflow.
6. 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.
• Google Cloud Storage bucket access if using STORAGE_BACKEND=google.
• Google Document AI settings if using DOCUMENT_AI_BACKEND=google.
• 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 hostname from K8S_DEPLOY_TARGETS.
• After Terraform changes to hosts, namespaces, static IPs, resource settings, or upload bucket names, update K8S_DEPLOY_TARGETS before redeploying the backend.
• 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.