Welcome to Green Web Foundation Platform documentation!

Welcome to the documentation for the Green Web platform. This site project contains documentation for the code for serving:

• the admin interface used by hosting provider, at admin.thegreenwebfoundation.org

• the API that serves requests at api.thegreenwebfoundation.org

This site also provides a summary of the other main libraries maintained by the Green Web Foundation, namely co2js, a javascript library for understanding and managing the carbon emissions from software, and the green web grid-intensity libraries, designed to help design carbon aware digital services that respond to the carbon intensity conditions on the electricity grids the internet relies on.

Getting started

Need to get going quickly? Start with installation steps, see the answers to common questions, and if you need to push changes for review visit the deployment instructions.

• Installation
  • Development on a remote machine using Github Codespaces
    • Why Github Codespaces
    • Setting up a Github Codespace
    • Sharing a view of your environent
  • Development on a local machine
  • The supported approach - using uv and just
  • Working locally with devpod
    • Installing just and installing uv
    • Installing system dependencies
      • Running system dependencies with docker compose
      • Object storage for accessing static files in staging and production
    • Running the application locally
    • Working with common tasks
      • Running custom tasks with just
        • Overriding environment variables
  • Working with email
  • Working with Docker
• How to…
  • Debug issues on production and staging
  • Run tests using pytest
    • Run all tests
    • Run all test until one fails
  • Set up Gitpod environment
    • Fetch files from object storage
• Deployment
  • Overview
    • What is happening with each automated deploy via Github Actions?
      • Once a workflow starting with tests begins running
    • Representing this process visually
  • Manual Deployment with Ansible
    • Standard Deployment Process
    • When to Deploy Manually
    • Manual Deployment Commands
    • If you need to make changes to how Github actions are set up
      • Main CI Workflow (.github/workflows/ci.yml)
      • Test Workflow (.github/workflows/test.yml)
      • Deploy Workflow (.github/workflows/deploy.yml)
      • Setup Environment Action (.github/actions/setup-environment)
    • Note on MyST Markdown Syntax
    • Understanding our infrastructure
      • Other relevant links:
    • how our web servers are deployed
      • A model closer to production - 4 sync workers
      • 2 workers, each with 2 threads
    • Workers
      • Typical queue operation - serving fast and slow responses
    • Scaling processes with ansible
    • Logging
    • Gunicorn logging
• Key concepts
  • What green energy means in this context
• Users and permissions
  • User accounts
    • Creating a user account
    • Quirks
  • User permissions
    • Groups
    • Object-level permissions
• Verification request
  • What is a verification request?
  • How to access the verification request form?
  • How is the form implemented?
  • Working with WizardView
  • Quirks of Django forms
    • Working with file upload in the form
    • Working with error messages
    • Preview implementation details
  • Testing the verification request
    • Testing the form wizard end to end
    • Testing focussed steps of the form wizard
• Understanding checks for green sites
  • Making this more specific
    • Domain to provider, via a Linked Domain.
      • Why do it this way?
    • Domain, to IP to provider, by IP range
      • Linking directly to a provider by IP range
      • Linking a site to a provider in the site’s supply chain
    • Domain, to IP to provider, by ASN
      • Linking directly to a provider by ASN
      • Linking a site to a provider in the site’s supply chain
• Understanding the life cycle of a Green Check Request
  • When a result has been cached for a domain
  • When a result has not been cached for a domain (or the cache is requested to be refreshed)
  • Greencheck images
• Automated Importers
  • Two moving parts - NetworkImporter and a CloudImporter
    • NetworkImporter
    • CloudImporters
    • Checking that importers work as expected:
  • Running the import from the command line
  • Adding new importers
  • Further Reading
• Other Green Web software
  • CO2.js
  • Grid intensity libraries - golang and javascript
  • Web Extension
• Working with the Green Web Open Data
• Working with Docker
  • How do use docker and docker compose for development
    • Running a local version of the full system with docker compose
    • Running a local version of the django app docker
  • Making new images
  • Publish an image
• Recurring tasks on the Green Web Platform
• Weekly imports
  • Defining the cronjob
  • Checking that the cronjobs are on the server
• Daily Green Domain Exports
• Troubleshooting
  • Our runbook - steps to follow when dealing with a live issue in production
  • Connecting a django instance to production / staging
  • Sentry
  • Style and coding conventions.
    • See also: