GDS Hub is an internal documentation tool for the Government Digital Service (GDS). It is a server-rendered web app backed by a database, and content can be edited in the browser.
This repository is a rewrite of the current Hub. It is being built in phases, which are set out in docs/build-plan.md. At the moment it is a foundation skeleton: an Express server with configuration, logging, a health check, tests and a container setup.
- Node.js 24 and TypeScript (strict mode, ES modules)
- Express 5
- PostgreSQL 18
- Vitest for unit tests and Playwright for end-to-end tests
- Docker and Docker Compose
Later phases add Nunjucks with the GOV.UK Design System (govuk-frontend), Drizzle ORM, Terraform and AWS ECS.
You need:
- Node.js 24 and npm
- Docker with Docker Compose
- Playwright installed locally.
npx playwright install
Install the dependencies:
npm installThis builds the app image and starts two containers, one for the app and one for the PostgreSQL database (db):
docker compose up -dCheck it is running:
curl http://localhost:3000/healthYou should get a response like:
{ "status": "ok", "version": "local", "uptime": 12 }To stop everything, run docker compose down. Add -v to delete the database volume as well.
-
Copy the example environment file:
cp .env.example .env
-
Start the containers by following Run the app with Docker.
-
Load the environment variables
set -a; . ./.env; set +a
-
Create the tables and load the synthetic sample data:
npm run db:reset
-
Start the app in watch mode:
npm run dev
The app restarts when you change a file in src/. It runs at http://localhost:3000.
npm run db:reset is all you need to get a local database ready for development. It applies the migrations and loads synthetic sample data (made-up values only). Run it again whenever you want to start from a clean, seeded database. It reads DATABASE_URL from .env.
| Command | What it does |
|---|---|
npm run db:reset |
Drops the app's tables, applies the migrations and seeds the data |
npm run db:generate |
Generates a new migration from changes to the Drizzle schema |
npm run db:migrate |
Applies pending migrations only, without seeding or dropping |
npm run db:seed |
Loads the synthetic sample data only |
db:reset and db:seed only run against a local database (localhost, 127.0.0.1, [::1] or db). db:reset also checks what is in the database before it drops anything. It refuses if the database has tables this app doesn't create, imported data, or rows with no audit record of being created. If it refuses, run docker compose down -v to delete the database volume, then start the database again with docker compose up -d db and run npm run db:reset.
Migrations must be backward compatible (expand, then contract). After changing the schema, run npm run db:generate and commit the generated SQL.
The migration loads the current Hub's built HTML and YAML data files into the database. See docs/migration.md for the steps, and docs/migration-validation.md to check it works without the real files.
- Use a separate, empty database for migrated data. The loader refuses any database that has ever been seeded, so seed data and migrated data never mix.
npm run migrate:loadis a dry run unless you add--apply.- Never commit the inputs, the reports or any migrated data.
npm run check:no-migration-datachecks this before every commit and in CI.
All configuration comes from environment variables. The app checks them when it starts. If a value is missing or invalid, it lists every problem and refuses to start.
| Variable | Default | Description |
|---|---|---|
NODE_ENV |
development |
development, test or production |
PORT |
3000 |
Port the app listens on |
LOG_LEVEL |
info |
debug, info, warn or error |
APP_VERSION |
dev |
Version reported by /health |
DATABASE_URL |
none | Required. A postgres:// or postgresql:// connection URL |
Docker Compose also reads these from .env:
| Variable | Default | Description |
|---|---|---|
APP_HOST_PORT |
3000 |
Port on your machine that serves the app |
DB_HOST_PORT |
5432 |
Port on your machine that serves PostgreSQL |
Never commit .env or any real credentials. In AWS, secrets come from Secrets Manager.
| Command | What it does |
|---|---|
npm run dev |
Starts the app in watch mode |
npm run build |
Compiles TypeScript from src/ to dist/ |
npm start |
Runs the compiled app from dist/ |
npm run lint |
Runs ESLint and checks formatting with Prettier |
npm run format |
Fixes formatting with Prettier |
npm run typecheck |
Type-checks the app, the tests and the config files |
npm test |
Runs the Vitest unit tests |
npm run test:e2e |
Builds the app, starts it on port 3100 and runs Playwright tests |
npm run db:reset |
Sets up the local database with migrations and sample data |
The other database commands are in Database. The migrate:* and check:no-migration-data commands are in docs/migration.md.
Before you open a pull request, run:
npm run lint && npm run typecheck && npm test && npm run test:e2eThe same checks run on every pull request in GitHub Actions (.github/workflows/test.yml), and must pass before the pull request can be merged. The workflow reads the Node version from engines.node in package.json and uses the same Postgres image as docker-compose.yml, so change those files rather than the workflow when versions change.
src/
app.ts builds the Express app (does not start a server)
server.ts loads config, starts the server and handles shutdown
config.ts reads and validates environment variables
db/ database schema, seed data and the db:* scripts
migration/ the inventory, load and verify scripts for the current Hub's data
lib/ shared code, such as the logger
middleware/ Express middleware, such as request IDs and request logging
routes/ route handlers
types/ TypeScript type declarations
test/
unit/ Vitest tests (*.test.ts)
e2e/ Playwright tests (*.spec.ts)
docs/
build-plan.md the phased build plan
progress/ progress.md (summary of each phase) and progress-phase<N>.md (full handover per phase)
backlog.md ideas that are out of scope for now
Requests flow from routes to services to repositories to the database. Only repositories talk to the database, and every write creates an audit log entry.
The app writes structured JSON logs, one line per entry, to standard output. Every request gets an ID. The app reuses a valid X-Request-Id header if one is sent, or makes a new ID, and returns it in the X-Request-Id response header. Each request's log entries include that ID, so you can trace a request through the logs.
Use the shared logger in src/lib/logger.ts rather than console.log.
docker compose up fails with "port is already allocated" or "address already in use"
Another program on your machine is already using port 3000 or 5432, often a local PostgreSQL. Choose a different host port in .env:
DB_HOST_PORT=5433
DATABASE_URL=postgres://gdshub:gdshub@localhost:5433/gdshub
To find out what is using a port, run lsof -nP -iTCP:5432 -sTCP:LISTEN.
The app exits straight away with "invalid configuration"
A required environment variable is missing or invalid. The log message names each one. Check your .env file and make sure you loaded it into your shell.
Pages are empty or fail with "relation does not exist"
The database isn't set up. Run npm run db:reset.
npm run db:reset says "refusing to reset"
The database holds something db:reset won't throw away, and the message says what. To start again, run docker compose down -v, then docker compose up -d db and npm run db:reset.
- Work follows the phases in docs/build-plan.md.
- Write all user interface text in British English and follow the GOV.UK style guide.
- Every page must meet WCAG 2.2 AA and work without JavaScript.
- Never commit data from the current Hub, exports or database dumps. Tests use made-up sample data only.
- After each phase, add a handover note in
docs/progress/progress-phase<N>.mdand a summary in docs/progress/progress.md.