Skip to content

Latest commit

 

History

History
159 lines (107 loc) · 3.79 KB

README.md

File metadata and controls

159 lines (107 loc) · 3.79 KB

IQB Streamlit Prototype

Streamlit-based dashboard prototype for the Internet Quality Barometer (IQB) project.

Automatic Deployments

The dashboard is automatically published using Cloud Run:

Trigger Environment URL
Push to sandbox-* branch Sandbox https://iqb.mlab-sandbox.measurementlab.net/
Merge pull request Staging https://iqb.mlab-staging.measurementlab.net/

Use sandbox deployments to see experimental changes or share them with a colleague for feedback.

To see recent builds:

gcloud builds list --project=mlab-sandbox --limit=10

To see a build logs:

gcloud builds log {BUILD_ID} --project=mlab-sandbox

Change the project to mlab-staging for the staging environment.

Prerequisites

  • Python 3.13 (see .python-version at repo root)

  • uv installed (see root README.md)

Running Locally

# Enter into the prototype directory if you're in the repository root
cd prototype

# Sync dependencies (creates .venv if needed)
uv sync --dev

# Run the Streamlit app
uv run streamlit run Home.py

The app will be available at: http://localhost:8501

If you make changes to Home.py or any other file in this directory, Streamlit will reload on save.

Project Structure

prototype/
├── Home.py              # Main Streamlit entry point
├── app_state.py         # Application state management
├── session_state.py     # Session state management
├── pages/               # Streamlit multi-page app pages
├── cache/               # Static data cache (JSON files per country)
├── utils/               # Helpers (data loading, calculations, constants)
├── visualizations/      # Chart and UI components (sunburst, etc.)
├── natural_earth/       # GeoJSON extraction for map visualizations
├── pyproject.toml       # Dependencies (streamlit, pandas, mlab-iqb)
├── Dockerfile           # Container image for Cloud Run
└── README.md            # This file

Testing with Docker

To test the Dockerfile locally before deploying:

# Build the image (from repo root)
cd ..
docker build -f prototype/Dockerfile -t iqb-prototype:test .

# Run the container
docker run --rm -p 8501:8501 iqb-prototype:test

# Access at http://localhost:8501
# Press Ctrl+C three or more times to stop

To run in background:

# Start container
docker run -d -p 8501:8501 --name iqb-test iqb-prototype:test

# Check logs
docker logs iqb-test

# Stop container
docker stop iqb-test
docker rm iqb-test

Manual Deployment

For manual deployment to Cloud Run using Cloud Build:

# From the directory containing cloudbuild.yaml
gcloud builds submit --config=cloudbuild.yaml --project=mlab-sandbox

This will:

  1. Build the Docker image from prototype/Dockerfile

  2. Push to Artifact Registry

  3. Deploy to Cloud Run in us-east1 region

Configuration: See cloudbuild.yaml for deployment settings (memory, CPU, region).

Permissions required:

  • roles/editor - Deploy and update services

  • roles/run.admin - Make new services public (see below)

Making the service public:

If deploying a new service or if you get 403 errors, an admin needs to run this command:

gcloud run services add-iam-policy-binding iqb-prototype \
  --region=us-central1 \
  --member="allUsers" \
  --role="roles/run.invoker" \
  --project=mlab-sandbox

This IAM policy persists across deployments, so it's only needed once.

Dependencies

The prototype depends on:

  • streamlit - Web framework

  • pandas - Data manipulation

  • numpy - Numerical operations

  • mlab-iqb - IQB library (from ../library, managed via uv workspace)

Dependencies are locked in the workspace uv.lock at the repository root.