Skip to main content

Frontend on App Engine

Frontend deployment lives in orphaned-wells-ui/deployment/app-engine.

Each collaborator frontend has its own App Engine service, branch-triggered GitHub Actions workflow, backend URL secret, dispatch route, DNS records, custom domain, and OAuth configuration.

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

Add or update an App Engine service​

Add an App Engine service config:

deployment/app-engine/app-<collaborator>.yaml

Copy an existing app-*.yaml file and update the service value. Existing services use the <collaborator>-uow naming pattern:

service: <collaborator>-uow
runtime: python310

Add a deployment workflow​

Add a frontend workflow:

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

Copy an existing collaborator deployment workflow and update:

  • Workflow name.
  • Trigger branch.
  • Job name.
  • app_yaml.
  • collaborator.
  • Backend URL secret name.

The workflow calls .github/workflows/deploy-dispatch.yml, which builds the React app and deploys the configured App Engine service.

The frontend repository must have DEPLOYMENT_SERVICE_KEY_JSON configured from the deployment service account. Terraform CI uses separate WIF identities. See Create Google service-account keys and GitHub Secrets and Variables.

The deployment account needs App Engine deploy and traffic-promotion access. The frontend workflow runs gcloud app deploy with the default promotion behavior, so roles/appengine.deployer alone is not enough. It also needs roles/appengine.serviceAdmin to update the App Engine service traffic split, plus the Cloud Build, Cloud Storage, and Service Account User roles listed in the GCP setup guide.

Add the backend URL secret​

Add a frontend repository secret:

<COLLABORATOR>_BACKEND_URL

The value should be the public backend URL and must not include a trailing slash:

https://<collaborator>-server.uow-carbon.org

Deploy the frontend​

Deploy by pushing to the workflow's configured branch, or run the workflow manually if the workflow supports manual dispatch.

The deployment workflow writes the build-time React environment values:

  • REACT_APP_BACKEND_URL
  • REACT_APP_GOOGLE_CLIENTID
  • REACT_APP_COLLABORATOR

If deployment uploads a new version but fails while promoting it to default, grant roles/appengine.serviceAdmin to the deployment service account and rerun the workflow. Deploying with --no-promote avoids that permission only when you intentionally do not want the new version to receive traffic.

Add the App Engine dispatch route​

Add the hostname to deployment/app-engine/dispatch.yaml:

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

Deploy the dispatch file from the App Engine deployment directory:

cd orphaned-wells-ui/deployment/app-engine
gcloud app deploy dispatch.yaml

Configure DNS and custom domain​

In Google Cloud DNS, add records for:

<collaborator>.uow-carbon.org

Use the same frontend IPv4 and IPv6 addresses as the other frontend instances:

  • A record for IPv4.
  • AAAA record for IPv6.

Then add <collaborator>.uow-carbon.org in App Engine custom domains.

Update OAuth​

In Google OAuth credentials, add both frontend URLs wherever frontend origins are required:

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

Use the exact URL format required by the OAuth client. Avoid trailing slashes unless the existing entries use them.

Verify​

After deployment:

  • Visit https://<collaborator>.uow-carbon.org.
  • Confirm the frontend calls the expected backend URL.
  • Confirm sign-in works for the custom domain.
  • Confirm the App Engine dispatch route sends the host to the expected service.