Skip to content

Deployment

Jump to bottom
Evan Prodromou edited this page Mar 25, 2024 · 1 revision

This page describes how we do deployment to our development, testing, and production environments.

Development

This environment tracks the latest changes in the develop branch. It may be unstable during regular development sprints.

When a new commit is pushed to the develop branch, one or more GitHub actions occurs.

  • global-api-develop: Runs if Global API files are changed. It builds the Global API ghcr.io/open-earth-foundation/citycatalyst-global-api:latest Docker image, runs migration scripts, and redeploys the development global api.
  • web-develop: Runs if Web UI or API files are changed. It builds the Web app ghcr.io/open-earth-foundation/citycatalyst:latest Docker image, runs migration scripts, seeders, and syncs, and redeploys the Web app.

Test

This environment is for acceptance testing by our product team and QA by our QA partners.

A release candidate version is made at the end of each sprint (right before demo).

To make a release candidate, take the following steps:

  1. In the develop branch, in the app directory, run npm version to find out the current development version -- usually "X.Y.0-dev" or "X.Y.0-dev.0".
  2. Run npm version vX.Y.0-rc.0 to update the package files to have the release candidate version.
  3. Commit the package files, package.json and package-lock.json
  4. Run git tag vX.Y.0-rc.0 to tag the repo at this level.
  5. git push to push to GitHub.
  6. In the app directory, run npm version vX.Z.0-dev.0 where Z = Y + 1. (In other words, increment the minor version).
  7. Commit the package files, package.json and package-lock.json.
  8. Run git tag vX.Z.0-dev.0 to tag the repo at the beginning of the next development cycle.
  9. git push to push to GitHub.
  10. git push --tags to push tags, too.
  11. git checkout main
  12. git merge vX.Y.0-rc.0 will merge the release candidate.
  13. git push should push to main and deploy the test code.

Deployment happens when there is a new commit pushed to main. These scripts run:

  • global-api-test: Runs if Global API files are changed in the main branch. It builds the Global API ghcr.io/open-earth-foundation/citycatalyst-global-api:main Docker image, runs migration scripts, and redeploys the development global api.
  • web-test: Runs if Web UI or API files are changed. It builds the Web app ghcr.io/open-earth-foundation/citycatalyst:main Docker image, runs migration scripts, seeders, and syncs, and redeploys the Web app.

During testing, there may be bugs that are identified and need to be fixed before pushing to production. In this case, you can either make the changes in the main branch and push directly, or you can make them in the develop branch and then git cherry-pick them into main.

After making a change to main, you should increment the release candidate number rc.0, rc.1, rc.2, etc. using npm version and git tag.

Production

Our production version is the one used by real customers and for demos. It can be about 3-4 weeks behind the develop branch, depending how long the sprint cycle and test process are.

To release the test version to production, do the following:

  1. In the main branch, in the app directory, run the npm version command to get the current release-candidate version, like X.Y.Z-rc.N.
  2. Run npm version vX.Y.Z, without a pre-release tag.
  3. Commit packages files.
  4. Run git tag vX.Y.Z.
  5. git push main
  6. git push --tags.

Deployment happens when there is a new tag pushed without a pre-release tag (the "-something" at the end).

  • global-api-test: Runs if Global API files are changed in the main branch. It builds the Global API ghcr.io/open-earth-foundation/citycatalyst-global-api:stable and version-tagged Docker image, runs migration scripts, and redeploys the development global api.
  • web-test: Runs if Web UI or API files are changed. It builds the Web app ghcr.io/open-earth-foundation/citycatalyst:stable and version tagged Docker image, runs migration scripts, seeders, and syncs, and redeploys the Web app.

The Kubernetes deployments use the version number tagged images -- so compatible newly-pushed images will deploy, but incompatible versions (with a major version change) won't deploy automatically. Don't use "stable", use the versioned tags.

If there are hot patches needed for production, take these steps:

  1. Commit to main.
  2. In the main branch, in the app directory, run the npm version command to get the current release version, like X.Y.Z.
  3. Run npm version X.Y.W-rc.0, where W = Z + 1 (increment the patch version) and commit
  4. git tag vX.Y.W-rc.0 to tag it
  5. Push to main (will deploy to test)
  6. Test it.
  7. If additional changes are needed, make additional release candidates after each commit.
  8. Once the tests are correct, push to production as described above.
Clone this wiki locally