Getting started with the Supply Chain Sustainability School

Getting the Supply Chain Sustainability School running locally, what you need access to, and a first task that will teach you the parts that matter.

Read [[architecture]] first — it explains why there are two products in one repository.

What you need access to

Thing	Why
Bitbucket: `StrategiQ/www.supplychainschool.co.uk`	The repo, and the deploy pipelines
WP Engine	Hosting for production and staging; SFTP credentials live as Bitbucket repository variables
A Moodle staging account (Titus Learning)	You cannot log into the front end without one — there are no WordPress user accounts for members
Companies House API key	Only needed if you are working on supplier upload or company lookup
A database dump from staging	The `cc_*` tables and the questionnaire configuration are data; an empty install has no reporting years, so the Carbon Calculator shows “No reporting years available”

Local setup

The project runs on Local by Flywheel. The expected hostnames are supplychainschool.build and carbon.supplychainschool.build — both are in the staging allow-list at wp-content/themes/supplychainschool/inc/classes/LMSClient.php:5, which is what makes a local site talk to staging Moodle rather than production. If you use a different hostname, add it to that list or nothing will log in.

Create a Local site, then replace app/public with a clone of the repo. WordPress core is not in the repository (see .gitignore), so you need Local’s core files underneath.
Import the staging database and search-replace the URLs (better-search-replace is installed for this).
wp-config.php is gitignored — write your own. It must define the standard multisite constants plus: MOODLE_WS_TOKEN, COMPANIES_HOUSE_API_KEY, CARBONCALC_CARBON_BLOG_ID (6 locally), CARBONCALC_SKIP_AUTH, CARBONCALC_LMS_DEBUG. Get the values from a colleague or the password manager; never commit them.
Third-party plugins are not in the repo (wp-content/plugins/* is ignored, with !wp-content/plugins/carboncalc as the only exception). Copy the plugins directory from staging, or install them. ACF Pro and Contact Form 7 are hard requirements — the theme fatals or degrades badly without them.

Building assets

Compiled CSS and JS are committed, and there is no build step in CI, so whatever is in assets/ is what deploys. See [[build-and-deploy]].

Carbon Calculator theme — verified working on Node 22:

cd wp-content/themes/carboncalculator
npm install
npm run prod     # or npm run dev to watch

Gulp 4 + Tailwind + PostCSS. Finishes in under a second. Two deprecation warnings (legacy Sass JS API, fs.Stats) are expected and harmless.

Main theme — this does not currently build on a modern Node:

cd wp-content/themes/supplychainschool
npm run prod     # fails on Node 22

On Node 22 it dies with ReferenceError: primordials is not defined — Gulp 3 against a modern Node. Under Node 11 it gets further and then fails in node-sass with a missing binding for that environment, which means the committed node_modules was built against a different Node. Expect to need npm rebuild node-sass (or a full reinstall) under a Node that [email protected] supports — roughly Node 8–11. package.json claims node >= 10.9 and npm-shrinkwrap.json is committed, so respect the lockfile.

If you only need to change Carbon Calculator styling, you do not need the main theme build at all.

Orientation: where things are

Main site theme: wp-content/themes/supplychainschool — an _s/underscores derivative. functions.php requires everything in inc/.
Carbon Calculator UI: wp-content/themes/carboncalculator. Note its functions.php is 5,295 lines and contains the entire supply-chain REST API — supplier code is here, not in the plugin.
Carbon Calculator data, reports API and wp-admin: wp-content/plugins/carboncalc (52 PHP files, ~20k lines).
Custom URL routes (/log-in/submit, /log-out, /fetch-resources, /update-members) are rewrites dispatched from themes/supplychainschool/inc/routing.php, not WordPress pages.

Two READMEs exist. themes/carboncalculator/README.md is accurate and useful. themes/supplychainschool/README.md is the untouched underscores boilerplate — ignore it.

Verifying the install works

In this order, because each step depends on the last:

Front page of blog 1 loads with the mega menu.
/log-in → log in with a staging Moodle account. Check the moodlelogin cookie exists and its domain covers the Carbon subsite.
/my-company-emissions/ on the Carbon subsite shows either a dashboard or a clearly-worded gate message. Any of “Company not linked”, “No reporting years available” or a ?cc_access_error= redirect is a working install with incomplete data — see [[carbon-access-gates]].
wp-admin → Carbon Calculator → User Lookup, search your own account. This replays every access gate read-only and is the fastest way to understand why the front end behaves as it does.
Tail wp-content/carboncalc-login-denied.log for the audit trail.

A sensible first task

Turn the site banner on and change its text: wp-admin → Carbon Calculator → Settings, then look at plugins/carboncalc/includes/SiteBanner.php and themes/carboncalculator/partials/site-banner.php. Small, safe, visible, and it walks you through the Carbon settings/FeatureSettings pattern and the multisite option routing that trips everyone up.

After that, read [[carbon-access-gates]] properly. Most support questions on this project are “why can this person not get in”, and that page plus the User Lookup screen answers nearly all of them.

Things that will surprise you

There are no WordPress accounts for members. Identity is Moodle. See [[moodle-sso-and-sessions]].
Blog ids are hard-coded all over the place — which Moodle to talk to, which nav renderer, which tracking id, which subsite holds the cc_* tables. Adding a subsite is a multi-file change.
There are no tests. None, anywhere, and no lint step in CI. Every feature page has a “what to run to know it still works” section; it is all manual.
The questionnaire is data, not code. Steps, fields, metrics and conversion factors are database rows loaded through a CSV importer. See [[reporting-year-config-and-importer]].
Production deploys are a manual Bitbucket pipeline, not a push to master.
Log files in wp-content/*.log are the primary debugging tool for the Carbon Calculator and nothing rotates them.