Skip to main content

Deploy New GCP Instance

Automated Backend VM Deployment Alternative

For an infrastructure-as-code approach to backend VM creation and DNS setup only, see Deploy with Terraform. Terraform automates the VM, static IP, and DNS record creation. You will still need to complete the NGINX, certificate, and GitHub Actions setup sections below.

This page describes the manual deployment flow for a new OGRRE instance on Google Cloud Platform. The backend VM setup steps can optionally be replaced with Terraform; all other steps remain the same.

Enter your collaborator name to update the example commands and deployment values throughout this page.

Live values
  • <collaborator>-uow-server
  • <collaborator>-server.uow-carbon.org
  • <collaborator>.uow-carbon.org
  • <COLLABORATOR>_BACKEND_URL
Live files
  • orphaned-wells-ui-server/.github/workflows/deploy-<collaborator>.yml
  • orphaned-wells-ui-server/nginx/<collaborator>/default.conf
  • orphaned-wells-ui/.github/workflows/deploy-<collaborator>.yml
  • orphaned-wells-ui/app-<collaborator>.yaml

Deploy New GCP Instance

This page describes the deployment flow for a new OGRRE instance on Google Cloud Platform, including backend VM setup, frontend App Engine deployment, DNS configuration, and MongoDB initialization.

Note: the collaborator value entered above is used to generate the example hostnames, workflow filenames, and deployment values throughout this page.

Backend Deployment

1. Create the Compute Engine VM

  • Create a new Compute Engine instance using the default settings.
  • Set the name to: <collaborator>-uow-server
  • Under access scopes, select Allow full access to all Cloud APIs.
  • Reserve a static external IP address for the instance.
  • Copy SSH keys from the other servers so you can log in.
  • Increase the boot disk size from 10 GB to 20 GB.

2. Configure the VM

SSH into the VM and install required packages.

sudo apt-get update sudo apt-get install -y gcc
  • Create the backend environment file in your home directory (~/.env or /home/<user>/.env) with the backend settings for this instance.
  • Install Docker following the standard Docker installation steps for Ubuntu.

3. Domain name and DNS

  • In Google Cloud DNS, add a new A record using the reserved static IP address.
  • Use the hostname: <collaborator>-server.uow-carbon.org
  • Ensure the DNS entry points to the VM’s static external IP.

4. Set up NGINX and Docker Compose

  • On the VM, add or copy the Docker Compose and NGINX configuration files.
  • The new collaborator should start with a simple default.conf that only defines the HTTP server block.
  • Start the stack:
sudo docker compose up -d
  • Verify NGINX started correctly:
sudo docker logs nginx

If you see a missing file or path error, it is likely from attempting HTTPS configuration before the certificate is available.

5. Request TLS certificates

After the HTTP configuration is running, create the certificate using Certbot:

sudo docker compose run --rm certbot certonly --webroot -w /var/www/certbot   --email mpesce@lbl.gov --agree-tos --no-eff-email   -d <collaborator>-server.uow-carbon.org --force-renewal
  • Update nginx/default.conf to add the HTTPS configuration.
  • Restart the containers:
sudo docker compose down sudo docker compose up -d

6. Renewal and cronjob

  • To renew certificates manually:
sudo docker compose run --rm certbot renew sudo docker compose exec nginx nginx -s reload

Add a cron job to check renewal daily at 3 AM:

crontab -e

Add the job:

0 3 * * * cd /home/mpesce && docker compose run --rm certbot renew && docker compose exec nginx nginx -s reload >> /var/log/certbot-renew.log 2>&1

This will run every day at 3 am and reload NGINX if certificates are renewed.

7. GitHub Actions and repo setup

  • Create a new workflow file in the backend repository:
    • orphaned-wells-ui-server/.github/workflows/deploy-<collaborator>.yml
  • Create a new NGINX config directory and default.conf for the collaborator:
    • orphaned-wells-ui-server/nginx/<collaborator>/default.conf
  • Use the other state files as a template and update all collaborator names accordingly.
  • Add the new backend server IP address to GitHub Actions secrets for the repository.
  • Deploy to the new VM by creating a new Git branch and pushing that branch.

Frontend Deployment

1. App Engine workflow

  • Add new workflow files for the frontend deployment:
    • orphaned-wells-ui/.github/workflows/deploy-<collaborator>.yml
    • orphaned-wells-ui/app-<collaborator>.yaml
  • Add the backend URL as a GitHub secret named <COLLABORATOR>_BACKEND_URL.
  • Make sure the URL has no trailing slash.
  • Deploy the frontend by pushing to the correct branch configured for that collaborator.

2. Domain name and dispatch

  • In orphaned-wells-ui/dispatch.yml, add the new URL route.
  • Deploy the dispatch file:
gcloud app deploy dispatch.yaml
  • Add a custom domain in App Engine.
  • Add DNS records for the frontend domain:
    • A record for <collaborator>.uow-carbon.org pointing to the frontend IPv4 address
    • AAAA record for the same hostname pointing to the frontend IPv6 address
  • Use the same addresses as the other frontend instances.
  • The dispatch.yml file defines how App Engine routes requests for the new URL.

3. Add custom domain and OAuth

  • Add the new custom domain record in Google Cloud App Engine.
  • In Google OAuth credentials, add both of the following as authorized origins and redirect URIs:
    • the App Engine autogenerated URL for the new deployment
    • the custom domain URL defined in dispatch.yml

Database Deployment - MongoDB

  • Use the InitializeMongo.py script available in the documentation to initialize the database.
  • Confirm that your new backend can connect to the MongoDB instance and that the required collections and indexes are created.

Notes

  • Keep the collaborator and hostname names consistent across VM naming, DNS records, workflow filenames, and configuration files.
  • For HTTPS rollout, always start with HTTP first, then request certificates and add HTTPS once the site is reachable.

Backend Deployment​

1. Create the Compute Engine VM​

2. Configure the VM​

3. Domain name and DNS​

4. Set up NGINX and Docker Compose​

5. Request TLS certificates​

6. Renewal and cronjob​

7. GitHub Actions and repo setup​

Frontend Deployment​

1. App Engine workflow​

2. Domain name and dispatch​

3. Add custom domain and OAuth​

Database Deployment - MongoDB​

Notes​

Additional Notes​

note

The sections above include everything needed for a complete deployment. If using Terraform, you can automate steps 1-3 (backend VM creation and DNS setup), but you must still complete steps 4-7 (NGINX, TLS certificates, and GitHub Actions setup), as well as frontend and database deployment.