The alpha prototype code now belongs in src/alpha-prototype. Support scripts remain in the root of the repository for running the prototype locally.
If you haven't already, install Docker on your computer.
If you don't have one already, sign up for a GitHub account and ask Andy to add you to the Register Dynamics organisation.
If you haven't already, install Github Desktop, Git Fork, or another git client and use it to clone this repository - here is a guide for how to do that in GitHub Desktop. This creates a local copy of the app on your computer.
Open the Terminal app to get a shell prompt, and go to the directory where you checked out the git repo. If you are familiar with the shell, you can use the cd command to go there; if not, you can drag the folder from the Finder into the terminal window and it should go there fore you.
Then type this command into the terminal window:
./run-alpha.shThis will build a docker container and run the app. Visit http://localhost:3000/ to see it. If it's not working, ask a somebody who's done this before and we'll figure it out and improve these instructions!
Press Ctrl+C in the shell to stop it.
The running container is given live access to the checked-out copy of the source code, so edits you make should be reflected immediately and not requiring rebuilding the thing.
For further information on GitHub Desktop (and how to use it to submit your changes back to the repository) can be found:
Please ensure to create a new branch for any work you do and push that to the repository - don't commit straight to the main branch, please!
Install Docker on your computer.
Running this command from a terminal:
./run-alpha.sh...will build a docker container and run the app. Visit http://localhost:3000/ to see it.
Press Ctrl+C in the shell to stop it.
The running container is given live access to the checked-out copy of the source code, so edits you make should be reflected immediately and not requiring rebuilding the thing.
In the include fake test data, the "Heart Age Assessment Tool" has evidence cards linking to documents, so search for that if you want to see them.
If you'd like to run it on a different port, run:
./run-alpha.sh -p PORT_NUMBERIf you'd like to use your own database rather than having one build from fake test data, put that database in a sqlite3 file called database.db and run:
./run-alpha.sh --use-my-dbYou can combine both options:
./run-alpha.sh -p PORT_NUMBER --use-my-dbIt's an NHS Prototype Kit app so look at their docs for details.
The build.sh script just builds a container based on node 24; the run-alpha.sh script runs build.sh and then runs it with $PWD mounted over /compass. Read them and the Dockerfile, there's no surprises.
In future we might make build.sh build two container images: one for prod use (with the site files actually built in) and one for dev use (with the files omitted as we'll mount them in, and a local database, and any automated test tools we want integreated). Then run-alpha.sh can use the latter.
The beta app belongs in src/beta-app. It is a separate app from the alpha prototype, and will be built and deployed separately.
- Node.js 26 or later
Run ./run-beta.sh to run the beta app. It will be available at http://localhost:3001/.
The first time you run it, it won't have any data - but while it's running (in a separate terminal window) you can run the ./load-fake-data.sh script to load a bunch of fake data into the database. It will stay there when you restart, you don't need to do this every time (but see below for instructions to blank the database if you want to reload some new fake data).
There is a test user seeded into the database for logging in to the beta app:
- Username:
test@example.com - Password:
northsouth
If you want to add your own users, you can do so by adding them to the users table in the database. Passwords must be hashed using Argon2id, which can be done using the generate-password-hash script in src/beta-app/scripts/generate-password-hash.ts. For example, to generate a hash for the password mypassword, run:
node scripts/generate-password-hash.js mypasswordand then use that value in the password_hash column when adding a new user to the users table.
To get a psql CLI prompt connected to the backend database:
docker exec -ti compass-beta-db-1 psql -U compass compassTo blank the database, causing it to be regenerated next time you run the beta, run this while the beta isn't running:
(cd src/beta-app ; docker compose down --volumes)The database's port is also exposed on the host machine, meaning you can access it using a Postgres client of your choice using postgresql://compass:password@localhost:5432/compass.
To get a bash shell in the app container:
docker exec -ti compass-beta-web-1 bashWithin src/beta-app, run the following commands to execute and watch tests or generate coverage:
npm run test- run all tests oncenpm run test:watch- start Vitest in watch modenpm run test:coverage- run tests with coverage reporting
Test files should be colocated with implementation using the .test.ts suffix (e.g., index.test.ts for index.ts).
Tests will need a database connection available (see the next section for details), but the ./test-beta.sh script will start the dockerised beta and run the tests within it, providing its own postgresql server with fake data loaded. Run the ./test-beta.sh script for instructions, it has a bunch of options and will do nothing but list them if run without any options!
This is an explainer of all the npm run scripts available for the beta app.
Those that are marked as needing database connnection details in the environment expect the following variables to be set:
DATABASE_NAMEDATABASE_USERDATABASE_HOSTDATABASE_PASSWORD_FILE
...pointing at the database name, login name, host, and the path to a file containing the password to access postgresql database.
npm run dev:css- start the CSS watcher for developmentnpm run dev:js- start the JS watcher (frontend) for developmentnpm run dev:ts- start the TypeScript watcher (backend) for developmentnpm run dev:db- start the database container for development (in detached mode)npm run dev- start the app in development mode with watch mode enabled for CSS, JS, and TypeScript changes. Needs database connection details in the environment.
npm run build:css- build the CSS for productionnpm run build:js- build the JS (frontend) for productionnpm run build- build the app for productionnpm run start- start the built app in production mode. Needs database connection details in the environment.
npm run type-check- run TypeScript type checkingnpm run lint- run ESLint to check for code style and potential errorsnpm run format:check- run Prettier to format the code according to the project's style guidenpm run lint:fix- run ESLint and automatically fix fixable issuesnpm run format- run Prettier and automatically fix fixable formatting issues
These all require database connection details in the environment, apart from generate:sitemap.
npm run test:all- run all tests oncenpm run test- run all tests oncenpm run test:watch- start Vitest in watch modenpm run test:coverage- run tests with coverage reportingnpm run test:pa11y- run accessibility tests using Pa11y (assumes target test instance of app is running)npm run test:a11y- run accessibility tests using Pa11y (launches local test instance of app)npm run generate:sitemap- generate the sitemap for the app to be used with Pa11ynpm run test:e2e- run end-to-end tests using Playwrightnpm run test:e2e:ui- run end-to-end tests using Playwright with a UI browser interface
npm run db:migrate- apply pending database schema changes fromsrc/beta-app/database/external-schemaandsrc/beta-app/database/app-schema. Needs database connection details in the environment.