Backend API Local Development

Setting up and running backend-api locally with auto-start

Backend API Local Development

This guide explains how to set up and run the backend-api locally with automatic startup when serving gograb-space or space-admin applications.

Prerequisites

Before you begin, ensure you have:

Environment Setup

1. Create .env.local File

Create a .env.local file in the project root directory with the following variables:

# MongoDB Configuration
MONGODB_CONNECTION_STRING=mongodb+srv://username:[email protected]/
MONGODB_DATABASE=gograb-api

# AI Provider API Keys
OPENAI_API_KEY=your-openai-key-here
ANTHROPIC_API_KEY=your-anthropic-key-here
GOOGLE_API_KEY=your-google-key-here

# JWT Configuration
JWT_SECRET=your-secure-jwt-secret-here
JWT_EXPIRATION=7d

# Server Configuration
PORT=3000
NODE_ENV=development

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:5200,http://localhost:5300

2. Generate JWT Secret

Generate a secure JWT secret using Node.js:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Copy the output and paste it as your JWT_SECRET value in .env.local.

3. MongoDB Configuration

Ensure your MongoDB connection string:

Auto-Start Configuration

The backend-api is configured to automatically start when you serve gograb-space or space-admin applications.

How It Works

Both apps/gograb-space/project.json and apps/space-admin/project.json have the backend-api configured as a dependency:

"serve": {
  "executor": "@angular-devkit/build-angular:dev-server",
  "dependsOn": ["backend-api:serve"],
  ...
}

This means:

Starting the Application

Option 1: Start gograb-space (includes backend-api)

nx serve gograb-space

You should see output indicating:

  1. Backend-api starting first
  2. Backend-api running on http://localhost:3000/api
  3. gograb-space starting on http://localhost:5200

Option 2: Start space-admin (includes backend-api)

nx serve space-admin

You should see output indicating:

  1. Backend-api starting first
  2. Backend-api running on http://localhost:3000/api
  3. space-admin starting on http://localhost:5300

Option 3: Start backend-api only

If you want to run just the backend-api:

nx serve backend-api

Testing Locally

1. Health Check Endpoint

Test the health endpoint to verify the backend is running:

curl http://localhost:3000/api/health

Expected response:

{
  "status": "ok",
  "timestamp": "2025-01-15T12:00:00.000Z",
  "service": "backend-api",
  "version": "1.0.0"
}

2. Root Endpoint

Test the root API endpoint:

curl http://localhost:3000/api

3. Authentication Endpoints

Register a new user:

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Test123!",
    "name": "Test User"
  }'

Login:

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Test123!"
  }'

Save the returned accessToken for authenticated requests.

4. AI Endpoints (Requires Authentication)

Test OpenAI endpoint:

TOKEN="your-jwt-token-here"

curl -X POST http://localhost:3000/api/ai/openai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "model": "gpt-4o-mini",
    "maxTokens": 50
  }'

Demo Page

A demo page is available to test backend connectivity:

http://localhost:5200/backend-api-status

This page provides:

Troubleshooting

Backend Not Starting

Issue: Backend-api doesn't start automatically

Solution:

  1. Check that .env.local exists in the project root
  2. Verify all required environment variables are set
  3. Check if port 3000 is already in use:
    lsof -i :3000
  4. Clear NX cache and try again:
    npx nx reset

MongoDB Connection Errors

Issue: Cannot connect to MongoDB

Solution:

  1. Verify MongoDB connection string is correct
  2. Ensure special characters in password are URL-encoded
  3. Check that your IP address is whitelisted in MongoDB Atlas
  4. Verify network connectivity

CORS Errors

Issue: CORS errors when accessing backend from frontend

Solution:

  1. Verify ALLOWED_ORIGINS includes your frontend URL
  2. Ensure no trailing slashes in ALLOWED_ORIGINS
  3. Restart backend-api after changing CORS configuration

JWT Errors

Issue: JWT validation fails

Solution:

  1. Verify JWT_SECRET is set in .env.local
  2. Ensure the token hasn't expired
  3. Check that the token is being sent in the Authorization header

Port Already in Use

Issue: Port 3000 is already in use

Solution:

  1. Find and kill the process using port 3000:
    lsof -i :3000
kill -9 <PID>
  2. Or change the port in .env.local:
    PORT=3001
  3. Update frontend environment files to match the new port

Development Tips

Hot Reload

The backend-api supports hot reload during development. Changes to backend files will automatically restart the server.

Logging

Monitor backend logs in the terminal where you ran the serve command. Logs include:

Environment Variables

Changes to .env.local require restarting the backend-api:

  1. Stop the serve process (Ctrl+C)
  2. Start again with nx serve gograb-space or nx serve space-admin

Testing with Multiple Apps

You can only run one app at a time that depends on backend-api:

Next Steps

Related Documentation