Installation

System Requirements

Before installing the EPR LAPS Backend API, ensure your system meets these requirements:

Required

Node.js >= v22.16.0
npm >= v11.0.0
MongoDB >= 5.0 (for local development)

Installation Methods

Local Installation
Docker Installation

Local Installation

Install Node.js

Install Node.js using nvm (recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install Node.js v22
nvm install 22
nvm use 22

# Verify installation
node --version  # Should be >= v22.16.0
npm --version   # Should be >= v11.0.0

Clone Repository

Clone the EPR LAPS Backend repository:

git clone <repository-url>
cd epr-laps-backend

Use Correct Node Version

The project includes an .nvmrc file. Use it to automatically switch to the correct Node version:

nvm use

If you see “version not installed”, run nvm install first.

Install Dependencies

Install all project dependencies:

npm install

This will install:

Production dependencies from package.json
Development tools (ESLint, Prettier, Vitest)
Husky git hooks for code quality

The installation automatically runs npm run setup:husky to configure git hooks.

Install MongoDB

Install MongoDB for local development:

# Using Homebrew
brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community

Verify Installation

Verify all components are installed:

# Check Node.js
node --version

# Check npm
npm --version

# Check MongoDB connection
mongosh --eval "db.adminCommand('ping')"

# View available npm scripts
npm run

Docker Installation

Install Docker

Install Docker and Docker Compose:

# Install Docker Desktop for Mac
# Download from: https://www.docker.com/products/docker-desktop

Clone Repository

Clone the repository:

git clone <repository-url>
cd epr-laps-backend

Build Development Image

Build the Docker development image:

docker build --target development --no-cache --tag epr-laps-backend:development .

Build Production Image

Build the production image:

docker build --no-cache --tag epr-laps-backend .

Start with Docker Compose

Use Docker Compose for complete local environment:

docker compose up --build -d

This starts:

EPR LAPS Backend on port 3001
MongoDB on port 27017
Redis on port 6379
Localstack (AWS services) on port 4566

Verify Docker Installation

Check running containers:

# List containers
docker compose ps

# View logs
docker compose logs -f epr-laps-backend

# Test API
curl http://localhost:3001/health

Configuration

Environment Variables

The API uses environment variables for configuration. Create a .env file or export these variables:

# Node Environment
NODE_ENV=development

# Server Configuration
HOST=0.0.0.0
PORT=3001

# MongoDB Configuration
MONGO_URI=mongodb://127.0.0.1:27017/
MONGO_DATABASE=epr-laps-backend

# Authentication
DEFRA_ID_DISCOVERY_URL=http://localhost:3200/cdp-defra-id-stub/.well-known/openid-configuration
DEFRA_ID_ISSUER=http://localhost:3200/cdp-defra-id-stub

# FSS API Integration
FSS_API_URL=http://localhost:3003/api
FSS_API_KEY=some-api-key
FSS_API_ENCRYPTION_KEY=your-base64-encryption-key

Configuration Schema

The API uses Convict for configuration management with validation:

// From src/config.js
import convict from 'convict'
import convictFormatWithValidator from 'convict-format-with-validator'

const config = convict({
  serviceName: {
    doc: 'Api Service Name',
    format: String,
    default: 'epr-laps-backend'
  },
  port: {
    doc: 'The port to bind',
    format: 'port',
    default: 3001,
    env: 'PORT'
  },
  mongo: {
    mongoUrl: {
      doc: 'URI for mongodb',
      format: String,
      default: 'mongodb://127.0.0.1:27017/',
      env: 'MONGO_URI'
    },
    databaseName: {
      doc: 'database for mongodb',
      format: String,
      default: 'epr-laps-backend',
      env: 'MONGO_DATABASE'
    }
  }
})

config.validate({ allowed: 'strict' })

Configuration validation runs on startup. Invalid configuration will prevent the server from starting.

Package Dependencies

The API uses the following core dependencies:

Production Dependencies

{
  "@hapi/hapi": "21.4.6",
  "@hapi/boom": "10.0.1",
  "hapi-auth-jwt2": "11.0.0",
  "mongodb": "7.1.0",
  "mongo-locks": "3.1.2",
  "joi": "18.0.2",
  "convict": "6.2.4",
  "pino": "10.3.1",
  "hapi-pino": "13.0.0",
  "undici": "7.22.0",
  "@defra/hapi-tracing": "1.30.0",
  "@defra/cdp-auditing": "0.6.0"
}

Development Dependencies

{
  "vitest": "4.0.18",
  "@vitest/coverage-v8": "4.0.18",
  "eslint": "9.29.0",
  "neostandard": "0.13.0",
  "prettier": "3.8.1",
  "nodemon": "3.1.14",
  "husky": "9.1.7"
}

Updating Dependencies

Keep dependencies up to date using npm-check-updates:

Install npm-check-updates

npm install -g npm-check-updates

Check for Updates

ncu --interactive --format group

Update Dependencies

# Update package.json
ncu -u

# Install updated packages
npm install

Run Tests

npm test

Running the Application

After installation, you can run the API in different modes:

# Start with hot-reload and debugging
npm run dev

# Server runs on http://0.0.0.0:3001
# Debug inspector available on port 9229

Code Quality Tools

Linting

The project uses ESLint with neostandard configuration:

# Check for linting errors
npm run lint

# Auto-fix linting errors
npm run lint:fix

Formatting

Prettier is configured for consistent code formatting:

# Check formatting
npm run format:check

# Auto-format code
npm run format

Git Hooks

Husky automatically runs quality checks before commits:

# Pre-commit hook runs:
# 1. npm run format:check
# 2. npm run lint

On Windows, if you encounter Prettier line break issues, run:

git config --global core.autocrlf false

Testing

The API uses Vitest for testing with coverage reporting:

# Run all tests with coverage
npm test

# Coverage reports are generated in ./coverage/

Troubleshooting

Installation fails with permission errors

On Linux/macOS, you may need to fix npm permissions:

# Change npm default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

MongoDB connection errors

Verify MongoDB is running and accessible:

# Test connection
mongosh mongodb://127.0.0.1:27017/

# Check MongoDB status
sudo systemctl status mongod

# Check Docker MongoDB
docker ps | grep mongo

Node version mismatch

Ensure you’re using Node.js v22:

# Check current version
node --version

# Switch to correct version
nvm use 22

# Or install if needed
nvm install 22

Husky hooks not working

Reinstall git hooks:

npm run setup:husky

# Or manually
npx husky install

Docker build fails

Clear Docker cache and rebuild:

# Remove old images
docker rmi epr-laps-backend:development epr-laps-backend

# Rebuild without cache
docker build --no-cache --tag epr-laps-backend .

Next Steps

Quick Start Guide

Get the API running and test your installation

API Reference

Explore available API endpoints and usage

Configuration

Deep dive into configuration options

Development Guide

Learn about development workflows and best practices

Get Started

Core Concepts

Development

Deployment

System Requirements

Required

Recommended

Installation Methods

Local Installation

Docker Installation

Configuration

Environment Variables

Configuration Schema

Package Dependencies

Production Dependencies

Development Dependencies

Updating Dependencies

Running the Application

Code Quality Tools

Linting

Formatting

Git Hooks

Testing

Troubleshooting

Next Steps

Quick Start Guide

API Reference

Configuration

Development Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Development

Deployment

​System Requirements

​Required

​Recommended

​Installation Methods

​Local Installation

​Docker Installation

​Configuration

​Environment Variables

​Configuration Schema

​Package Dependencies

​Production Dependencies

​Development Dependencies

​Updating Dependencies

​Running the Application

​Code Quality Tools

​Linting

​Formatting

​Git Hooks

​Testing

​Troubleshooting

​Next Steps

Quick Start Guide

API Reference

Configuration

Development Guide

Build docs developers (and LLMs) love

System Requirements

Required

Recommended

Installation Methods

Local Installation

Docker Installation

Configuration

Environment Variables

Configuration Schema

Package Dependencies

Production Dependencies

Development Dependencies

Updating Dependencies

Running the Application

Code Quality Tools

Linting

Formatting

Git Hooks

Testing

Troubleshooting

Next Steps