Getting Started

This guide walks you through setting up a local development environment for the eTeamups Platform from scratch. By the end you will have all microservices running on your machine and be able to make API requests through the Nginx gateway.

Prerequisites

Make sure the following tools are installed before you begin.

Verify your installations:

node -v          # v20.x.x or higher
npm -v           # 9.x.x or higher
docker --version # Docker version 24.x or higher
git --version
openssl version

1. Clone the Repository

git clone <repository-url> eteamups-platform
cd eteamups-platform

2. Install Dependencies

The project is a monorepo – a single npm install at the root pulls in everything for all services and shared libraries.

npm install

This installs production and development dependencies including TypeScript, Jest, Express, Mongoose, BullMQ, React Email, OpenTelemetry SDKs, and more.

3. Set Up Environment Variables

A reference environment file is provided at docker.local.env. Copy it to .env so that dotenv can pick it up at runtime:

cp docker.local.env .env

Review the contents and adjust values if necessary. The defaults are configured to work with the local Docker Compose stack out of the box. See the Environment Variables reference for a full description of every variable.

Important: Never commit your .env file to version control. The .gitignore already excludes it.

4. Generate SSL Certificates

The local Nginx container terminates HTTPS using self-signed certificates. Generate them with the provided script:

bash scripts/generate-ssl.sh

This creates ssl/nginx.crt and ssl/nginx.key in the project root. Your browser will show a certificate warning when accessing https://localhost:18443 – this is expected for self-signed certificates.

5. Start Local Dependencies

Start MongoDB, Redis, and Nginx as Docker containers:

npm run deps:start

This runs docker-compose -f docker-compose.local.yml up -d, which starts:

• MongoDB on port 27018 (mapped from container port 27017)
• Redis on port 6379
• Nginx on port 8080 (HTTP, redirects to HTTPS) and port 18443 (HTTPS)

Verify the containers are running:

npm run deps:check

You should see both eteamups-mongodb-local and eteamups-redis-local listed with status “Up”.

6. Seed the Database

Populate MongoDB with reference data (countries, industries, skills, education levels, and more):

npm run seed

The seeder reads .js seed files from services/store/src/seed/ and inserts them into the corresponding MongoDB collections.

7. Start All Services

You have two options:

Option A – Start services only (dependencies already running from step 5):

npm start

Option B – Start everything (dependencies + services in one command):

npm run dev

npm run dev starts the Docker containers, waits five seconds for them to initialise, then launches all services in parallel.

Both options start the following processes:

8. Verify Services Are Running

Health checks via direct service ports

Each service exposes a /_ping endpoint (returns 200 OK) and a /health endpoint (returns JSON {"status":"ok"}):

curl http://localhost:9000/_ping    # Auth
curl http://localhost:9100/_ping    # Profile
curl http://localhost:9107/_ping    # Organisation
curl http://localhost:9102/_ping    # Media

Health checks via the Nginx gateway

After Nginx is running, you can access services through the unified HTTPS gateway:

# Gateway root -- lists available services
curl -k https://localhost:18443/

# Service-specific through the gateway
curl -k https://localhost:18443/auth/_ping
curl -k https://localhost:18443/profile/_ping
curl -k https://localhost:18443/organisation/_ping
curl -k https://localhost:18443/media/_ping

The -k flag tells curl to accept the self-signed certificate.

Stopping Everything

To stop just the services (kill Node.js processes on service ports):

npm run kill

To stop the Docker containers:

npm run deps:stop

Quick Reference

Next Steps

• Project Structure – understand how the codebase is organised.
• Local Setup – deep dive into local development workflows.
• Environment Variables – full reference for all configuration values.