website.md

Emblem - Website

The Emblem Website code lives in its own directory.

Design

The Emblem Website is configured as a Cloud Run service written using the Flask web framework for Python.

The website uses the following Google Cloud services:

• Google Identity - handles user sign-in and authentication
• Secret Manager - manages OAuth client secrets
• Cloud Storage - stores session data

Emblem uses a testing & delivery pipeline to automate deployment of the web application (Website & Content API) and setup of operations management.

To deploy the Emblem Website manually, either launch the Quickstart interactive tutorial or follow the Setup guide below.

Interactive Walkthrough for Setup

Learn how to run the website by following an interactive tutorial on Cloud Shell, a free browser-based IDE that comes preconfigured with the necessary tools to run Emblem. Click the button below to clone Emblem into a Cloud Shell instance and launch the interactive tutorial:

Note: some elements of the website will not function without a deployed instance of the Emblem Content API. Learn how to run the Content API by launching the API Quickstart on Cloud Shell.

Manual Instructions for Setup

Deploy the website container to Cloud Run

1. Navigate to the directory website/.

2. Copy the client-libs/ directory located in root folder

   cp -rf ../client-libs/ .

3. Create an environment variable that contains your API server url and your Emblem session bucket name.

   export SITE_VARS="EMBLEM_API_URL=$EMBLEM_API_URL, EMBLEM_SESSION_BUCKET=$EMBLEM_SESSION_BUCKET"

4. Build an image with Cloud Build

   gcloud builds submit . --tag=gcr.io/$PROJECT_ID/website

5. Deploy to Cloud Run

   gcloud run deploy \
     --image=gcr.io/$PROJECT_ID/website \
     --set-env-vars "$SITE_VARS" website

Navigate to the URI provided upon successful deployment.

Setting up authentication

Note: end-user authentication is required to access some - but not all - application pages.

To enable end-user authentication within the application, you'll need to create an OAuth client ID and configure an OAuth consent screen.

If you don't already have an OAuth client set up, you can run the Emblem configure_auth script in your terminal:

sh ./scripts/configure_auth.sh

Configuration

To configure the app, set the following environment variables:

Variable name	Description
CLIENT_ID	The client ID of your OAuth 2.0 client.
CLIENT_SECRET	The client secret of your OAuth 2.0 client.
REDIRECT_URI	A redirect_uri authorized for your OAuth 2.0 client
EMBLEM_API_URL	A URL pointing to your instance of the Emblem Content API
EMBLEM_SESSION_BUCKET	The name of your Cloud Storage bucket.

The CLIENT_ID and CLIENT_SECRET can be found in the details page of your Credentials dashboard.

Note: these are sensitive values that should be kept secure. When deployed with the production pipeline, Emblem uses Secret Manager to store these values more securely.

The EMBLEM_API_URL value will be determined by where you host the Content API. (If you're using Cloud Run, it will look something like https://<SERVICE_NAME>-<HASH>.run.app)

Congratulations! You are now ready to run the Emblem web app.

Running Locally

Downloading tools

To run this project, you'll need the following tools:

• Python (3.9 or higher)
• pip

The following tools are optional, but recommended:

• pyenv

Installing dependencies

To install dependencies for the website, cd into the website directory and run pip install -r requirements.txt.

Manual Setup

Complete the steps as documented above:

1. Navigate to the directory website/.

2. Copy the client-libs/ directory located in root folder

   cp -rf ../client-libs/ .

3. Set up the Cloud-based identity provider for your local app

4. Configure the service via environment variables

Running

Use the flask run to run the website locally.

By default, the website will run on port 8080.

Seeding the Database

If your site is missing default content, see the Content API instructions to seed the database.