Skip to main content

​
Quick start

Get the entire QeetMart platform running on your local machine in about 15 minutes.
This guide will start all microservices, databases, and optionally the frontend applications.

​
Prerequisites

Before starting, ensure you have these tools installed:
  • Node.js 22.x or later (download)
  • pnpm 10.x or later (npm install -g pnpm)
  • Java 17 or later (OpenJDK)
  • Go 1.23 or later (download)
  • Docker with Docker Compose v2 (download)
1

Clone the repository

git clone https://github.com/qeetgroup/qeetmart.git
cd qeetmart
2

Install dependencies

Install all Node.js dependencies across the monorepo:
pnpm install
This installs dependencies for:
  • API Gateway
  • Web, Admin, and Mobile apps
  • Shared packages
  • Documentation platform
3

Create environment files

Copy example environment files for each service:
cp micros/api-gateway/.env.example micros/api-gateway/.env
cp micros/auth-service/.env.example micros/auth-service/.env
cp micros/user-service/.env.example micros/user-service/.env
cp micros/product-service/.env.example micros/product-service/.env
cp micros/inventory-service/.env.example micros/inventory-service/.env
The example files contain development credentials. These are NOT suitable for production use.
4

Start the backend stack

Launch all services and databases with Docker Compose:
pnpm docker:up
This command:
  • Builds Docker images for all services
  • Starts PostgreSQL databases (auth_db, user_db, product_db, inventory)
  • Starts Redis for inventory caching
  • Launches API Gateway on port 4000
  • Starts all microservices with health checks
First run takes 3-5 minutes to build images. Subsequent starts are much faster.
5

Verify service health

Check that all services are running correctly:
# Check API Gateway health
curl http://localhost:4000/health

# Check all services status
curl http://localhost:4000/health/services

# Check Inventory service directly
curl http://localhost:8080/health
Expected response from /health:
{
  "status": "ok",
  "service": "api-gateway",
  "timestamp": "2026-03-03T10:30:00.000Z"
}
6

Start frontend apps (optional)

Run any of the frontend applications:
pnpm dev:web
# Opens at http://localhost:3000
Or run everything together:
# Runs gateway + web + admin in parallel
pnpm dev

​
Service endpoints

Once running, these endpoints are available:
ServiceURLDescription
API Gatewayhttp://localhost:4000Main entry point for all APIs
Gateway Healthhttp://localhost:4000/healthGateway health check
Service Healthhttp://localhost:4000/health/servicesAll services status
Gateway Infohttp://localhost:4000/infoService registry information
Auth Servicehttp://localhost:4001Direct auth service access
User Servicehttp://localhost:8082Direct user service access
Product Servicehttp://localhost:8083Direct product service access
Inventory Servicehttp://localhost:8080Direct inventory service access
Web Apphttp://localhost:3000Customer-facing web application
Admin Panelhttp://localhost:5173Admin dashboard

​
Understanding the API Gateway

The API Gateway (micros/api-gateway/src/index.ts:1) handles:
  • Request routing - Proxies requests to appropriate microservices
  • Authentication - JWT validation for protected routes
  • Rate limiting - 1000 requests per minute per IP by default
  • CORS - Cross-origin request handling
  • Error handling - Unified error responses

​
Gateway route mapping

API routes are mapped to services in micros/api-gateway/src/config/services.ts:55: 
[
  { path: '/api/v1/auth', service: 'auth', upstreamPath: '/auth' },
  { path: '/api/v1/users', service: 'users', upstreamPath: '/users' },
  { path: '/api/v1/products', service: 'products', upstreamPath: '/products' },
  { path: '/api/v1/inventory', service: 'inventory', upstreamPath: '/inventory' },
]

​
Docker Compose configuration

The docker-compose.dev.yml file defines the complete stack: 
services:
  gateway:
    build:
      context: .
      dockerfile: micros/api-gateway/Dockerfile
    environment:
      PORT: "4000"
      AUTH_SERVICE_URL: "http://auth-service:4001"
      USER_SERVICE_URL: "http://user-service:8082"
      PRODUCT_SERVICE_URL: "http://product-service:8083"
      INVENTORY_SERVICE_URL: "http://inventory-service:8080"
    ports:
      - "4000:4000"
    depends_on:
      - auth-service
      - user-service
      - product-service
      - inventory-service

​
Common tasks

​
View logs

# All services
docker compose -f docker-compose.dev.yml logs -f

# Specific service
docker compose -f docker-compose.dev.yml logs -f gateway
docker compose -f docker-compose.dev.yml logs -f inventory-service

​
Check running containers

docker compose -f docker-compose.dev.yml ps

​
Restart a service

docker compose -f docker-compose.dev.yml restart gateway

​
Stop the stack

# Stop and remove containers, networks, volumes
pnpm docker:down

# Or directly with docker compose
docker compose -f docker-compose.dev.yml down -v

​
Development workflows

After initial setup, use these commands for daily development: 
# Build all apps
pnpm build

# Build specific apps
pnpm build:gateway
pnpm build:web
pnpm build:admin
pnpm build:docs

​
Troubleshooting

​
Services won’t start

Issue: Docker containers fail to start Solution: Check if ports are already in use 
# Check port usage
lsof -i :4000  # API Gateway
lsof -i :4001  # Auth Service
lsof -i :8080  # Inventory Service
lsof -i :8082  # User Service
lsof -i :8083  # Product Service

​
Database connection errors

Issue: Services can’t connect to PostgreSQL Solution: Wait for database health checks to pass 
# Check database container status
docker compose -f docker-compose.dev.yml ps auth-db

# View database logs
docker compose -f docker-compose.dev.yml logs auth-db
Databases have health checks configured (docker-compose.dev.yml:38): 
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres -d auth_db"]
  interval: 5s
  timeout: 5s
  retries: 20

​
React 19 peer dependency warnings

Issue: pnpm shows peer dependency warnings during install Solution: These are expected. The root package.json includes peerDependencyRules to handle packages that haven’t updated to React 19 yet.

​
Build script approval warnings

Issue: pnpm warns about unapproved build scripts Solution: Run the interactive approval tool: 
pnpm approve-builds

​
Next steps

Explore the architecture

Understand how services communicate and data flows through the system

API documentation

Browse the API reference to start building integrations

Configuration guide

Learn about environment variables and service configuration

Deployment

Deploy QeetMart to Kubernetes using the provided manifests and Helm charts
All default credentials are set to postgres/postgres for local development. Always rotate these for any non-local environment.

Build docs developers (and LLMs) love

Get started for freeTalk to us