Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astrxnomo/shop-microservers/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, configuring your environment, and booting the entire Shop Microservers platform locally with Docker Compose. By the end you will have all four backend services, the Nginx gateway, and the Next.js frontend running on http://localhost — ready to register an account, browse the auto-seeded product catalog, and place your first order.

​
Prerequisites

Before you begin, make sure the following are available on your machine:
  • Docker and Docker Compose (Docker Desktop or Docker Engine ≥ 20.x)
  • Port 80 free on your host — or set GATEWAY_PORT in your .env file to an alternative port

​
Steps

1

Clone the repository

Clone the project from GitHub and navigate into the directory:
git clone https://github.com/astrxnomo/shop-microservers.git
cd shop-microservers
2

Configure your environment

Copy the example environment file and open it in your editor:
cp .env.example .env
At minimum, set a strong value for JWT_SECRET. All other defaults are suitable for local development:
# Database
POSTGRES_USER=shop
POSTGRES_PASSWORD=shop
CATALOG_DB_NAME=catalog
ORDERS_DB_NAME=orders

# JWT — change this to a long random string
JWT_SECRET=your-secret-here

# Gateway
GATEWAY_PORT=80

# Frontend
NEXT_PUBLIC_API_URL=http://localhost
3

Start the full stack

Build all images and start every service in the correct dependency order:
docker compose up --build
Docker Compose will start the databases first, wait for their health checks to pass, then bring up the four microservices, followed by the gateway and finally the frontend. The catalog service automatically seeds 12 products on first boot — you will see seed output in the catalog container logs.
4

Open the application

Once all containers are healthy, open your browser and navigate to:
http://localhost
If you changed GATEWAY_PORT, use http://localhost:<GATEWAY_PORT> instead.
5

Register an account

Navigate to the registration page and create your account:
http://localhost/register
The auth service issues a JWT on successful registration. The frontend stores it in localStorage and uses it for all subsequent authenticated requests.
6

Browse, add to cart, and place an order

With your account created, you are ready to use the full shopping flow:
  • Browse the 12 auto-seeded products on the home page
  • Add items to your cart — the cart service stores your selections in Redis with a 7-day TTL
  • Navigate to /orders and complete checkout — the orders service will verify stock, decrement it in the catalog, persist the order, and clear your cart in one atomic operation

​
Rebuilding a single service

If you make changes to one service and want to rebuild only that container without restarting the entire stack, use: 
docker compose up --build <service>   # auth | catalog | cart | orders | frontend
This is useful during development when iterating on a single service in isolation.

​
Stopping and resetting

To stop all containers gracefully: 
docker compose down
To stop all containers and delete all volumes (this wipes every database and Redis cache, giving you a completely clean slate): 
docker compose down -v
Running docker compose down -v is irreversible — all PostgreSQL data and Redis cart data will be permanently deleted. The catalog will re-seed on the next docker compose up --build.
The catalog service’s seed script is idempotent — it checks whether products already exist before inserting, so restarting the stack without -v will never create duplicate products.

Build docs developers (and LLMs) love

Get started for freeTalk to us