Skip to main content

​
Get Started in 5 Minutes

This guide will help you quickly set up and run the EPR LAPS Backend API on your local machine.
1

Prerequisites

Ensure you have the required tools installed:
  • Node.js >= v22.16.0
  • npm >= v11
  • MongoDB (or use Docker Compose)
We recommend using nvm to manage Node.js versions.
If using nvm, switch to the correct Node.js version:
cd epr-laps-backend
nvm use
2

Clone and Install

Clone the repository and install dependencies:
git clone <repository-url>
cd epr-laps-backend
npm install
The installation will automatically set up Husky git hooks for code quality checks.
3

Configure Environment

Set up your environment variables. Create a .env file or export the following:
export NODE_ENV=development
export PORT=3001
export HOST=0.0.0.0
export MONGO_URI=mongodb://127.0.0.1:27017/
export MONGO_DATABASE=epr-laps-backend
export DEFRA_ID_DISCOVERY_URL=http://localhost:3200/cdp-defra-id-stub/.well-known/openid-configuration
export DEFRA_ID_ISSUER=http://localhost:3200/cdp-defra-id-stub
export FSS_API_URL=http://localhost:3003/api
export FSS_API_KEY=some-api-key
Never commit sensitive values like FSS_API_KEY or FSS_API_ENCRYPTION_KEY to version control.
4

Start the Server

Run the API in development mode:
npm run dev
The server will start on http://0.0.0.0:3001 with hot-reloading enabled.
Development mode includes:
  • Automatic restart on file changes (via nodemon)
  • Debug inspector on port 9229
  • Pretty-printed logs
5

Verify Installation

Test the API is running by checking the health endpoint:
curl http://localhost:3001/health
Expected response:
{
  "status": "ok"
}

​
Alternative: Docker Compose

For a complete local development environment with all dependencies, use Docker Compose:
1

Start Docker Environment

Launch the entire stack:
docker compose up --build -d
This starts:
  • EPR LAPS Backend API on port 3001
  • MongoDB on port 27017
  • Redis on port 6379
  • Localstack (AWS services) on port 4566
2

Verify Services

Check all services are running:
docker compose ps
Test the API:
curl http://localhost:3001/health
3

View Logs

Monitor application logs:
docker compose logs -f epr-laps-backend
4

Stop Environment

When finished:
docker compose down

​
Available Scripts

The following npm scripts are available for development: 
# Start with hot-reload and debugging
npm run dev

# Start with breakpoint debugging
npm run dev:debug

​
Test the API Endpoints

Once running, you can test the API endpoints:

​
Health Check

curl http://localhost:3001/health

​
Bank Details (requires authentication)

curl http://localhost:3001/bank-details/LA123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Documents (requires authentication)

curl http://localhost:3001/documents/LA123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
For authenticated endpoints, you’ll need to obtain a valid JWT token from your Defra ID provider.

​
Development Features

​
Hot Reloading

The development server uses nodemon to automatically restart when you modify:
  • JavaScript files (.js)
  • JSON files (.json)

​
Debug Mode

Connect a debugger to port 9229: 
# VS Code launch.json
{
  "type": "node",
  "request": "attach",
  "name": "Attach to Process",
  "port": 9229,
  "restart": true
}

​
MongoDB Locks

For write operations requiring locks: 
import { createServer } from './server.js'

const server = await createServer()

async function doStuff(server) {
  const lock = await server.locker.lock('unique-resource-name')

  if (!lock) {
    // Lock unavailable
    return
  }

  try {
    // Perform write operations
  } finally {
    await lock.free()
  }
}

​
Proxy Configuration

The API includes forward-proxy support using undici: 
import { fetch } from 'undici'

// Automatically uses proxy if HTTP_PROXY env var is set
const response = await fetch('http://localhost:3001/data')

​
Troubleshooting

Ensure MongoDB is running:
# Check if MongoDB is running
mongosh --eval "db.adminCommand('ping')"

# Or use Docker Compose
docker compose up -d mongodb
Change the port via environment variable:
export PORT=3002
npm run dev
Update your global git config:
git config --global core.autocrlf false
Reinstall dependencies:
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Installation Guide

Detailed installation and configuration instructions

API Reference

Complete API endpoint documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us