Dashboard Setup

This page provides instructions on how to setup and develop ESD dashboard applications. Contact #esd-tech-help if you need any assistance.

Project Setup & Dashboard Generation

Using the GitHub Template

The recommended way to create a new dashboard application is to use our GitHub template repository. This uses a hybrid approach combining GitHub templates with cookiecutter automation.

Steps:

Navigate to the template repository:
Go to cust-infrastructure-dimensions-app-template
Create a new repository:
Click "Use this template" → "Create a new repository"
Choose a descriptive repository name (e.g., my-funding-dashboard)
Add a description
Choose visibility (typically private or internal)
Click "Create repository"
Run the template workflow:
Go to the Actions tab in your new repository
Click on "Setup Project from Template" workflow
Click "Run workflow" button
Configure your project components:
- Project name: (optional) Defaults to your repository name
- Include dashboard: true to generate a Dash dashboard application
- Docset-based dashboard: true for dashboards using docset templates, false for simple dashboards
- Include JWT authentication: true to add authentication middleware
- Include pipeline: true to also generate a Cloud Run pipeline component
Click "Run workflow"
Wait for generation:
The workflow will take a few minutes to generate your project structure. You can watch the progress in the Actions tab.

Start developing:

$ cd dashboard  # or pipeline/ if you included it
$ uv sync

Developing your Dashboard

📖 For comprehensive development guidance, see the Development Guide which covers architecture, data management, custom components, and best practices.

To test the sample Dash dashboard app:

$ cd dashboard
$ uv sync
$ make dash_dev_server

Or run directly with uv:

$ cd dashboard
$ uv sync
$ uv run python app.py

Check the running app at http://localhost:8050

Creating Pages

Create individual .py files for each page in your app, and put them in the /pages directory.

In each of these page files add a dash.register_page(__name__), which tells Dash that this is a page in your app. Define the page's content within a variable or a function layout that returns the content.

# in app.py
app = Dash(__name__, use_pages=True)

Add dash.page_container in your app layout where you want the page content to be displayed when a user visits one of the app's page paths.

Use ds.AppContainer object to define the layout:

import ds_dash_support as ds
from dash import Dash, html, page_container


app = Dash(__name__, use_pages=True)


app.layout = ds.AppContainer(
    children=[
        html.H1("Dash App Tutorial", id="title", className="small-header"),
        page_container,
    ],
    title="Dash App"
    )

Deployment

The CI/CD pipeline automatically deploys your dashboard when you push to specific branches:

develop branch → https://esd-dev.ds-analytics.com/{dashboard-name}/
staging branch → https://esd-staging.ds-analytics.com/{dashboard-name}/
main branch → https://esd.ds-analytics.com/{dashboard-name}/

Complete one-time workflow setup:
Whenever you are ready to deploy, you need to request a Github Runner for your repository by reaching out to #esd-tech-help and then move workflow files to activate an existing CI/CD:

$ git clone git@github.com:digital-science/your-repo-name.git
$ cd your-repo-name
$ mv file-name.yml .github/workflows/
$ git add .github/workflows/
$ git commit -m "ci: activate CI/CD workflows"
$ git push

Configuring the Application in Dimensions

For a Dimensions app to be fully functional, it has to be configured within the Dimensions integration layer and application. To request this, open an issue in the ESD team Jira space. Once this is available, you can begin testing your app in Dimensions.

Advanced Options

Your app may need additional environment variables at runtime, for example API keys. In these cases you will want to override the default deploy workflow and service.yaml template to pass additional environment variables to Cloud Run. These variables also need to be defined within the GitHub project by updating the GitHub Actions variables.

For example, to add a new environment variable called MY_API_KEY, add the following to the .github/workflows/deploy.yml to pass environment variables to the deploy step:

# In .github/workflows/deploy.yml
env:
  MY_API_KEY: ${{ secrets.MY_API_KEY }}

And update the service.yaml.jinja2 file to pass the new environment variable to Cloud Run:

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: {{ name }}
  labels:
    cloud.googleapis.com/location: {{ region }}
  annotations:
    run.googleapis.com/ingress: all
spec:
  template:
    metadata:
      annotations:
        {% if stage == "prod" %}autoscaling.knative.dev/minScale: '1'{% endif %}
        run.googleapis.com/vpc-access-connector: projects/{{ project }}/locations/us-central1/connectors/central-serverless
    spec:
      timeoutSeconds: 1800
      serviceAccountName: dim-app@{{ project }}.iam.gserviceaccount.com
      containers:
        - env:
            - name: STAGE
              value: {{ stage }}
            - name: GCP_PROJECT
              value: {{ project }}
            - name: GBQ_DATASET
              value: funding_paths
            - name: MY_API_KEY
              value: {{ my_api_key }}
          image: {{ image }}
          startupProbe:
            httpGet:
              path: /{{ name }}/ready
            initialDelaySeconds: 10
          resources:
            limits:
              cpu: '1'
              memory: 1G