Deploying
Deploy to Google App Engine
Cloud Carbon Footprint is able to be deployed using serverless options such as Google App Engine. To deploy to App Engine's Standard Environment, you will first have to do the following:
- Install the gcloud CLI
- Have access to a project and service account with the correct permissions
- Google Cloud Project with an App Engine Application created
We will be deploying Cloud Carbon Footprint using App Engine's Standard Environment with Node.js.
Deploying to App Engine will involve uploading your source files to Google Cloud Storage where your app will be deployed and built using the Cloud Build service. For this process to work, you must have Cloud Build enabled in your project and assign the Storage Object Viewer
permission to the Cloud Build service account.
Make sure to also configure your gcloud environment to target the project where you intend to deploy your App Engine services: gcloud config set project [project-name]
Deploy API
Navigate to the
packages/api
directory of your CCF project. There will already be anapp.yaml
file configured with the App Engine runtime information for the API service. You are welcome to modify this file to determine your instance and other configurations.Make sure you have already followed the steps to connect your data and have created a
.env
with your app's configurations.If fetching GCP estimates, App Engine will attempt to use the default App Engine service account assigned to your App Engine instance unless the
GOOGLE_APPLICATION_CREDENTIALS
variable is set in your.env
file. If this is desired, make sure to assign the least permissions needed for querying your Billing Data as noted when Connecting your Data to GCP.The default App Engine configuration in your
app.yaml
file sets the logging mode to use Google Cloud's Cloud Logging service to integrate CCF's logging experience with the native App Engine logger. Make sure that the service account used has permissions for creating and writing logs.Deploying to App Engine will require building, extracting, and preparing your app to be deployed to App Engine's NodeJS environment. Fortunately, we have made a script to make these steps easier for you and to ensure that certains tools such as the yarn version used is made compatible for App Engine's build steps. You can manually execute the steps in the script or simply execute the following command in your terminal
./appengine-deploy.sh
to run the script.This script will do the following:
- Build the API application
- Copy the source files into a temporary directory
- Copy environment variables in your
.env
file to the temp directory - Configure App Engine's compatible Yarn version and install dependencies
- Deploy to App Engine using the
gcloud app deploy
command.
If in a linux environment and facing permission errors when executing the script, you may need to provide the script execution permissions using:
chmod -x ./appengine-deploy.sh
.If you wish to see a summary of the services to deploy as shown in the example below, you can manually run
gcloud app deploy
in your terminal and the gcloud util will show a preview reflecting your current configurations in yourapp.yaml
file. Make sure the summary matches your desired configuration. If you intend to use the script, exit usingctrl+c
otherwise the build will fail. If running the commands manually and have already executed the steps above, you can hitenter
to confirm and begin the deployment.Services to deploy:
descriptor: [/home/cloud-carbon-footprint/packages/api/app.yaml]
source: [/home/cloud-carbon-footprint/packages/api]
target project: [cloud-carbon-footprint]
target service: [default]
target version: [20231215t144836]
target url: [https://api-dot-cloud-carbon-footprint.ue.r.appspot.com]
target service account: [[email protected]]If running manually, you can use the
--version
flag to specify a specific version ID for your deployment. Otherwise, a timestamp-based one will be generated as shown in the example.Google Cloud will begin building your application and deploying it to app engine. When it is finished, the link to your deployed service will be provided or you can access it by running the
gcloud app browse
command. If no custom routing is configured, it will deploy tohttps://[version]-dot-[project-name].[region].r.appspot.com
.
By default, secrets stored in your local .env
file will be deployed to your App Engine instance. If you wish to have a more robust solution for managing your secrets within Google Cloud, you can store your secrets by adding your variables to the app.yaml
file's env_variable
section, or check out other Google Cloud Secret Management solutions.
Deploying with Github Actions
Cloud Carbon Footprint is also configured to be deployed to Google App Engine (standard environment) using GitHub Actions. See the Hello World example for instructions on setting up a Google Cloud Platform project and installing the Google Cloud SDK to your local machine.
Before deploying, you'll need to build the application and create the packages/api/.env and packages/client/.env file as mentioned above and in our Getting Started section. There are two scripts to populate these files as part of the GitHub Actions pipeline: packages/cli/create_server_env_file.sh and client/create_client_env_file.sh.
Once you've set up the CGP project and have the command line tools, Cloud Carbon Footprint can be deployed with ./appengine/deploy-staging.sh
or ./appengine/deploy-production.sh
, depending on your environment.
Or if you want to use GitHub Actions, you can see the configuration for this in .github/workflows/ci.yml.
It will deploy to https://<something>.appspot.com
.
Deploy to AWS
The application can also be deployed in AWS by making use of EC2 as the compute service to run it on. In order to do so, we provide a basic infrastructure setup that spins up all the necessary cloud resources, from the required role/policies to the actual compute resource and its provisioning (EC2 with user data).
The infrastructure setup, developed with Terraform, can be found in terraform/aws
and needs to be parametrized with the right values and tweaked to the specific circumstances of the user i.e. there might not be the need to fire up all resources but a subset of them.
For more information, please note that there are specific instructions for this here.
Deploy to other cloud providers
Cloud Carbon Footprint should be deployable to other cloud providers such as Heroku or AWS Elastic Beanstalk. However, only Google App Engine has been tested currently, so there may be some work involved in doing this.
Don't forget to deploy your .env
files or otherwise set the environment variables in your deployment.