Local Development

Live Demo Version

For those looking to explore without installing, a live demo version of the assurance platform is available at https://assuranceplatform.azurewebsites.net/ . Please be aware that data in the demo environment is periodically cleared.

Setting up a local installation of the TEA Platform (e.g. for development) involves configuring the application and its database. The recommended approach is to use Docker, but you can also run locally without Docker if preferred.

Docker (Recommended)

A quicker way to get the TEA Platform running on your local machine is to use Docker. If you’re familiar with Docker and docker-compose, you can follow the Docker Quickstart guide to set up the platform with minimal effort.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v20 or later)
pnpm package manager
PostgreSQL (v14 or later)

Step-by-Step Installation

1. Clone the Repository


git clone https://github.com/alan-turing-institute/AssurancePlatform.git
cd AssurancePlatform

2. Install Dependencies


pnpm install

3. Set Up Environment Variables

Create a .env file in the root directory:


cp .env.example .env

Edit .env with your configuration:


# Database connection
DATABASE_URL="postgresql://username:password@localhost:5432/tea_dev"
 
# Authentication
NEXTAUTH_SECRET="your-secret-key"  # Generate with: openssl rand -base64 32
NEXTAUTH_URL="http://localhost:3000"
 
# GitHub OAuth (optional)
GITHUB_APP_CLIENT_ID="your-github-client-id"
GITHUB_APP_CLIENT_SECRET="your-github-client-secret"

To generate a unique string for the NEXTAUTH_SECRET you can run:


openssl rand -base64 32

4. Set Up the Database

Create a PostgreSQL database:


createdb tea_dev

Generate the Prisma client and run migrations:


npx prisma generate
npx prisma migrate dev

5. Run the Development Server


pnpm run dev

The application will be available at http://localhost:3000 .

Development Commands

Running Tests


pnpm run test           # Run all tests
pnpm run test:watch     # Run tests in watch mode
pnpm run test:coverage  # Run tests with coverage report

Database Management


# Generate Prisma client after schema changes
npx prisma generate
 
# Create a new migration
npx prisma migrate dev
 
# Reset database (drops all data)
npx prisma migrate reset
 
# Open Prisma Studio (database GUI)
npx prisma studio

Code Quality


# Lint and format code
pnpm exec ultracite fix
 
# Check for issues without fixing
pnpm exec ultracite check
 
# Type check
npx tsc --noEmit

Building for Production


pnpm run build
pnpm start

Troubleshooting

Database Connection Issues

If you encounter database connection errors:

Ensure PostgreSQL is running
Verify your DATABASE_URL in .env.local
Check that the database exists: psql -l | grep tea_dev

Node.js Version Issues

The TEA Platform requires Node.js v20 or later. Check your version with:


node --version

If you need to manage multiple Node.js versions, consider using nvm .