Development Environment

Prerequisites

Node.js v22 or higher is required to run this project. Older versions are not supported.

Verify your Node.js version:

node --version

If you need to upgrade, download the latest version from nodejs.org.

Installation Steps

Clone the repository

git clone https://github.com/GitRepoFabi/coderhouse-backendIII.git .

Install dependencies

npm install

This installs all production and development dependencies including:

Express.js for the API server
Mongoose for MongoDB interactions
Mocha, Chai, and Supertest for testing
Faker for mock data generation

Configure environment variables

Create a .env file in the project root with the required configuration:

PORT=8080
MONGO_URL=mongodb://127.0.0.1:27017
DB_NAME=adoptme

Start MongoDB

Ensure MongoDB is running locally on port 27017, or update MONGO_URL to point to your MongoDB instance.

Start the development server

npm run dev

This uses nodemon for automatic restart on file changes.

Environment Variables

The application uses dotenv to load configuration from a .env file. All environment variables are defined in src/config/config.js:

import dotenv from 'dotenv';

dotenv.config();

export default {
    PORT: process.env.PORT || 8080,
    MONGO_URL: process.env.MONGO_URL || 'mongodb://127.0.0.1:27017',
    DB_NAME: process.env.DB_NAME || 'adoptme'
}

Configuration Reference

Variable	Default	Required	Description
`PORT`	`8080`	No	Port number for the Express server
`MONGO_URL`	`mongodb://127.0.0.1:27017`	Yes	MongoDB connection URL
`DB_NAME`	`adoptme`	Yes	MongoDB database name

MONGO_URL and DB_NAME are critical. The application connects to MongoDB at startup and will fail if the database is unreachable.

Example Configurations

PORT=8080
MONGO_URL=mongodb://127.0.0.1:27017
DB_NAME=adoptme

NPM Scripts

The project includes several npm scripts for different use cases:

{
  "scripts": {
    "start": "node src/app.js",
    "dev": "nodemon src/app.js",
    "test": "mocha test/supertest.test.js --exit"
  }
}

Available Commands

Command	Description	Use Case
`npm start`	Start the production server	Production deployment
`npm run dev`	Start development server with nodemon	Local development
`npm test`	Run test suite with Mocha	Testing and CI/CD

Use npm run dev during development. Nodemon automatically restarts the server when you save file changes.

Development vs Production

Development Mode

npm run dev

Features:

Auto-restart on file changes (nodemon)
Detailed error messages
Local MongoDB connection
Verbose logging

Recommended Settings:

PORT=8080
MONGO_URL=mongodb://127.0.0.1:27017
DB_NAME=adoptme_dev

Production Mode

npm start

Features:

Single process (no auto-restart)
Optimized error handling
Remote MongoDB connection (MongoDB Atlas)
Production logging

Recommended Settings:

PORT=3000
MONGO_URL=mongodb+srv://user:[email protected]
DB_NAME=adoptme

MongoDB Setup

Local MongoDB

Install MongoDB Community Edition

Start the MongoDB service:

# macOS (with Homebrew)
brew services start mongodb-community

# Linux (systemd)
sudo systemctl start mongod

# Windows
net start MongoDB

Verify it’s running:
```
mongosh
```

MongoDB Atlas (Cloud)

Create a free cluster at mongodb.com/atlas
Add your IP address to the allowlist
Create a database user

Copy the connection string:

MONGO_URL=mongodb+srv://<username>:<password>@cluster.mongodb.net

Debugging Tips

Server Won’t Start

Check port availability:

# macOS/Linux
lsof -i :8080

# Windows
netstat -ano | findstr :8080

Solution: Kill the process using the port or change PORT in .env

Database Connection Errors

Error: MongoServerError: connect ECONNREFUSED Solutions:

Verify MongoDB is running
Check MONGO_URL in .env
Test connection with mongosh:
```
mongosh mongodb://127.0.0.1:27017
```

Environment Variables Not Loading

Error: Application uses default values instead of .env values Solutions:

Ensure .env is in the project root
Check file name (exactly .env, not env.txt or .env.local)
Restart the server after modifying .env

Test Failures

Error: Tests timeout or fail to connect Solutions:

Ensure MongoDB is running
Check that the database is accessible
Verify DB_NAME in .env
Run tests with increased timeout:
```
this.timeout(10_000); // 10 seconds
```

Docker Development

Building the Image

docker build -t adoptme-api:1.0.0 .

Running with Docker

docker run -p 8080:3000 \
  -e PORT=3000 \
  -e MONGO_URL=mongodb://host.docker.internal:27017 \
  -e DB_NAME=adoptme \
  adoptme-api:1.0.0

When running in Docker, use host.docker.internal instead of localhost to access the host machine’s MongoDB.

Docker Compose

Create a docker-compose.yml for a complete development stack:

version: '3.8'

services:
  api:
    build: .
    ports:
      - "8080:3000"
    environment:
      - PORT=3000
      - MONGO_URL=mongodb://mongo:27017
      - DB_NAME=adoptme
    depends_on:
      - mongo

  mongo:
    image: mongo:6
    ports:
      - "27017:27017"
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

Start the stack:

docker-compose up

Project Structure

adoptme-api/
├── src/
│   ├── app.js              # Application entry point
│   ├── config/
│   │   └── config.js       # Environment configuration
│   ├── dao/
│   │   └── models/         # MongoDB models
│   ├── mocks/
│   │   └── mocks.js        # Mock data generators
│   ├── routes/
│   │   ├── users.router.js
│   │   ├── pets.router.js
│   │   └── mocks.router.js
│   └── utils/              # Utility functions
├── test/
│   └── supertest.test.js   # API tests
├── .env                    # Environment variables (create this)
├── package.json
└── README.md

IDE Setup

VS Code Recommended Extensions

ESLint: Linting and code quality
Prettier: Code formatting
MongoDB for VS Code: Database exploration
REST Client: Test API endpoints
Thunder Client: Alternative API client

VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "javascript.preferences.quoteStyle": "single"
}

Common Development Workflows

Making Code Changes

Start development server: npm run dev
Make changes to source files
Nodemon automatically restarts the server
Test changes with REST client or browser

Adding New Endpoints

Create/modify router in src/routes/
Add tests in test/supertest.test.js
Run tests: npm test
Document in API reference

Testing Locally

Ensure MongoDB is running
Run test suite: npm test
Check test output for failures
Fix issues and re-run tests

Next Steps

Write automated tests for your changes
Generate mock data for development
Explore the API Reference to understand available endpoints
Set up CI/CD for automated testing and deployment

Get Started

Core Concepts

Testing & Development

Deployment

Development Environment

Prerequisites

Installation Steps

Environment Variables

Configuration Reference

Example Configurations

NPM Scripts

Available Commands

Development vs Production

Development Mode

Production Mode

MongoDB Setup

Local MongoDB

MongoDB Atlas (Cloud)

Debugging Tips

Server Won’t Start

Database Connection Errors

Environment Variables Not Loading

Test Failures

Docker Development

Building the Image

Running with Docker

Docker Compose

Project Structure

IDE Setup

VS Code Recommended Extensions

VS Code Settings

Common Development Workflows

Making Code Changes

Adding New Endpoints

Testing Locally

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Testing & Development

Deployment

​Prerequisites

​Installation Steps

​Environment Variables

​Configuration Reference

​Example Configurations

​NPM Scripts

​Available Commands

​Development vs Production

​Development Mode

​Production Mode

​MongoDB Setup

​Local MongoDB

​MongoDB Atlas (Cloud)

​Debugging Tips

​Server Won’t Start

​Database Connection Errors

​Environment Variables Not Loading

​Test Failures

​Docker Development

​Building the Image

​Running with Docker

​Docker Compose

​Project Structure

​IDE Setup

​VS Code Recommended Extensions

​VS Code Settings

​Common Development Workflows

​Making Code Changes

​Adding New Endpoints

​Testing Locally

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Environment Variables

Configuration Reference

Example Configurations

NPM Scripts

Available Commands

Development vs Production

Development Mode

Production Mode

MongoDB Setup

Local MongoDB

MongoDB Atlas (Cloud)

Debugging Tips

Server Won’t Start

Database Connection Errors

Environment Variables Not Loading

Test Failures

Docker Development

Building the Image

Running with Docker

Docker Compose

Project Structure

IDE Setup

VS Code Recommended Extensions

VS Code Settings

Common Development Workflows

Making Code Changes

Adding New Endpoints

Testing Locally

Next Steps