Skip to main content

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, and python.
  • 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​

ItemPattern
Collaborator key
Backend namespaceuow-<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​

  1. Create a MongoDB database and user for the collaborator (e.g., ogrre-<collaborator>), granting it read/write privileges on the new database.
  2. Download InitializeMongoDB.py (see Create and connect MongoDB database) and run it once to seed the required roles, teams, and initial admin users collections:
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)​

  1. Add the collaborator to terraform.tfvars and sync to CI: Pull the shared terraform.tfvars configuration from GCS:

    ./deployment/terraform/scripts/sync_tfvars.sh pull

    Add <collaborator> under gke_backends in deployment/terraform/terraform.tfvars:

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

    Upload the updated file to GCS and sync the PROD_TERRAFORM_TFVARS GitHub secret:

    ./deployment/terraform/scripts/sync_tfvars.sh push --secret
  2. Create the GitHub Environment and RUNTIME_ENV secret: Prepare a local <collaborator>.env file with the required runtime settings (the GKE deployment workflow automatically sets ENVIRONMENT, BACKEND_URL, STORAGE_BUCKET_NAME, service-account key paths, and worker sizing):

    COLLABORATOR=<collaborator>
    ALLOWED_ORIGINS=https://<collaborator>.uow-carbon.org

    DB_NAME=<DB_NAME>
    DB_CONNECTION=<DB_CONNECTION>
    DB_USERNAME=<DB_USERNAME>
    DB_PASSWORD=<DB_PASSWORD>

    REQUIRE_AUTH=true
    AUTH_PROVIDER=google
    token_uri=https://oauth2.googleapis.com/token
    client_id=<GOOGLE_OAUTH_CLIENT_ID>
    client_secret=<GOOGLE_OAUTH_CLIENT_SECRET>

    SESSION_COOKIE_DOMAIN=.uow-carbon.org
    SESSION_COOKIE_SECURE=true
    SESSION_COOKIE_SAMESITE=lax

    PROJECT_ID=tidy-outlet-412020
    LOCATION=us
    STORAGE_BACKEND=google
    DOCUMENT_AI_BACKEND=google
    USE_DB_SCHEMAS=true

    Because Google Cloud Console masks client_secret after creation and GitHub Actions secrets are write-only, you can copy the shared client_id and client_secret from another local .env file or read them from an existing GKE namespace such as uow-staging (see Inspecting Kubernetes resources with kubectl for one-time kubectl cluster 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 .env file as RUNTIME_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
  3. Register the collaborator in collaborators.json: Add <collaborator> to collaborators.json at the root of orphaned-wells-ui-server:

    [
    "osage",
    "newts",
    "isgs",
    "rrc",
    "<collaborator>"
    ]
  4. Merge to main and approve Terraform in GitHub Actions: Commit the collaborators.json update and merge it to main. Merging to main triggers the Deploy Staging Server to GKE workflow, which generates a Terraform plan for the new collaborator's bucket, namespace, static IP, and DNS records:

    1. In GitHub Actions (CATALOG-Historic-Records/orphaned-wells-ui-server), open the Deploy Staging Server to GKE run.
    2. Review the Terraform plan summary on the workflow run page.
    3. If everything looks correct, click Review deployments → terraform-apply → Approve and deploy and wait for the infrastructure apply job to finish before proceeding. (Note: The terraform-apply GitHub 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.)
  5. Create and push the collaborator branch: Create the <collaborator> branch from main and push it to trigger .github/workflows/deploy-k8s-collaborator.yml:

    git checkout main && git pull
    git 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)​

  1. Create the GitHub Environment and BACKEND_URL secret: Configure BACKEND_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"
  2. Update collaborators.json and dispatch.yaml: Add <collaborator> to collaborators.json at the root of orphaned-wells-ui:

    [
    "isgs",
    "newts",
    "osage",
    "rrc",
    "<collaborator>"
    ]

    Add the route for <collaborator>.uow-carbon.org/* to deployment/app-engine/dispatch.yaml:

    - url: "<collaborator>.uow-carbon.org/*"
    service: <collaborator>-uow

    Merge both changes to main.

  3. Create and push the collaborator branch: Create the <collaborator> branch from main and push it to trigger .github/workflows/deploy-collaborator.yml:

    git checkout main && git pull
    git checkout -b <collaborator> && git push -u origin <collaborator>

    The workflow automatically renders service: <collaborator>-uow using deployment/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:

  1. Deploy dispatch.yaml:
    cd orphaned-wells-ui/deployment/app-engine
    gcloud app deploy dispatch.yaml
  2. Add Frontend Cloud DNS Records: In Google Cloud DNS, add A (IPv4) and AAAA (IPv6) records for <collaborator>.uow-carbon.org using the same App Engine addresses as the existing frontend instances.
  3. 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.org to the <collaborator>-uow service.
  4. 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 host and ManagedCertificate domain are rendered from the Terraform target and require a backend deployment after Terraform apply.
  • No trailing slashes: Frontend BACKEND_URL secrets and OAuth origin entries should not have trailing slashes.
  • Keep both collaborators.json files updated: Ensure <collaborator> is added to collaborators.json in both orphaned-wells-ui-server and orphaned-wells-ui so push deployments and main → <collaborator> sync PRs are active across both repositories.