Skip to main content

​
Prerequisites

Before setting up the QeetMart development environment, ensure you have the following tools installed:
  • Node.js 22.x
  • pnpm 10.x
  • Java 17
  • Go 1.23+
  • Docker + Docker Compose v2
All services require specific versions of these tools. Using different versions may cause compatibility issues.

​
Installation steps

1

Clone the repository

Clone the QeetMart monorepo to your local machine:
git clone https://github.com/qeetgroup/qeetmart.git
cd qeetmart
2

Install dependencies

Install all workspace dependencies using pnpm:
pnpm install
This command installs dependencies for all packages and apps in the monorepo workspace.
3

Create environment files

Each service requires its own environment configuration. Copy the example files:
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 .env.example files contain safe defaults for local development. You can customize these values as needed.
4

Start the backend stack

Use Docker Compose to start all backend services and databases:
pnpm docker:up
This command starts:
  • API Gateway (Node.js/Express) on port 4000
  • Auth Service (Spring Boot) on port 4001
  • User Service (Spring Boot) on port 8082
  • Product Service (Spring Boot) on port 8083
  • Inventory Service (Go/Gin) on port 8080
  • PostgreSQL databases for each service
  • Redis for the inventory service
5

Verify services are running

Check that all services are healthy:
curl http://localhost:4000/health
curl http://localhost:4000/health/services
curl http://localhost:8080/health
You should receive successful responses from all endpoints.

​
Environment configuration

Each service has its own .env.example file located in its service directory: 
micros/api-gateway/.env.example
Never commit real secrets to .env files. The .env files are git-ignored by default. Always use environment-specific secret managers in deployment environments.

​
Service ports

ServiceRuntimePortHealth Endpoint
API GatewayNode.js/Express4000/health
Auth ServiceSpring Boot4001/actuator/health
User ServiceSpring Boot8082/actuator/health
Product ServiceSpring Boot8083/actuator/health
Inventory ServiceGo/Gin8080/health

​
Stopping services

To stop all Docker services and remove volumes: 
pnpm docker:down

​
Troubleshooting

​
Peer dependency warnings

The root package.json includes pnpm peer rules and package extensions to handle React 19 compatibility issues with upstream dependencies like swagger-ui-react.

​
Build script warnings

If you see warnings about build scripts, the root package.json includes pnpm.onlyBuiltDependencies with approved packages. To adjust approvals: 
pnpm approve-builds

​
Docker stack issues

To check the status of all services: 
docker compose -f docker-compose.dev.yml ps
To view logs for a specific service: 
docker compose -f docker-compose.dev.yml logs -f gateway

​
Next steps

Once your environment is set up, proceed to local development to learn about development workflows and commands.

Build docs developers (and LLMs) love

Get started for freeTalk to us