Get both microservices up and running in your local environment.
Prerequisites Before you begin, ensure you have the following installed:
Tool Minimum Version Python 3.10+ pip Latest Node.js 18+ npm 9+ Docker & Docker Compose 20+ / 2.0+ (optional)
Local Development Setup Python Service
Node.js Service
Docker (Full Stack)
Navigate to the Python service directory
Create and activate a virtual environment
python -m venv venv source venv/bin/activate
Install dependencies
pip install -r requirements.txt
Navigate to the Node service directory
Start all services with Docker Compose
docker-compose up --build
This will start:
Verify services are running
Check the Node.js health endpoint: curl http://localhost:3000/api/health
And verify Python service is running by accessing any endpoint: curl http://localhost:5000/api/products
Run the Tests Verify your setup by running the test suites:
Python Tests
Node.js Tests
All Tests
cd python-service source venv/bin/activate # macOS/Linux python -m pytest tests/ -v
chmod +x scripts/run_all_tests.sh ./scripts/run_all_tests.sh
Make Your First API Call
Register a new user
curl -X POST http://localhost:5000/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "securepassword123", "name": "John Doe" }'
Response: { "message" : "User registered successfully" , "user" : { "id" : 1 , "email" : "[email protected] " , "name" : "John Doe" , "role" : "customer" }, "access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }
Login and get JWT token
curl -X POST http://localhost:5000/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "securepassword123" }'
Save the access_token from the response for authenticated requests.
Create a product (authenticated)
curl -X POST http://localhost:5000/api/products \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "name": "Wireless Headphones", "description": "Premium noise-cancelling headphones", "price": 299.99, "stock": 50, "category": "electronics" }'
List all products (public endpoint)
curl http://localhost:5000/api/products
Response: { "products" : [ { "id" : 1 , "name" : "Wireless Headphones" , "description" : "Premium noise-cancelling headphones" , "price" : 299.99 , "stock" : 50 , "category" : "electronics" } ], "pagination" : { "page" : 1 , "per_page" : 20 , "total" : 1 , "pages" : 1 } }
Environment Configuration Both services use environment variables for configuration. For local development, the default values work out of the box.
Python Service
Node.js Service
Create a .env file in python-service/: FLASK_ENV = development SECRET_KEY = dev-secret-key DATABASE_HOST = localhost DATABASE_PORT = 5432
Create a .env file in node-service/: NODE_ENV = development PORT = 3000 JWT_SECRET = your-secret-key DB_HOST = localhost DB_PORT = 5432
For testing, both services automatically use SQLite in-memory databases, so you don’t need PostgreSQL running locally.
Troubleshooting
psycopg2-binary fails to install
This is expected for local development. The Python service uses SQLite for testing, so PostgreSQL dependencies are optional. Skip the error or install without PostgreSQL support: pip install -r requirements.txt --no-deps
ModuleNotFoundError: No module named 'app'
Make sure you’re running commands from the python-service/ directory, not the project root.
If port 5000 or 3000 is already in use, you can specify a different port: # Python FLASK_RUN_PORT = 5001 python run.py # Node.js PORT = 3001 npm start
sqlite3 build errors (Node)
If you encounter native module build errors for sqlite3: Or ensure you have native build tools installed (python, make, gcc).
Docker containers fail to start
Check if ports are available and no other containers are running: docker-compose down docker-compose up --build
Next Steps
Explore the Architecture Understand the microservices architecture and design decisions
API Reference Browse the complete API documentation for both services
Testing Guide Learn about the test suites and how to write tests
Deploy with Docker Deploy the full stack with Docker Compose