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.

The docker-compose.yml file at the project root defines and orchestrates the entire Shop Microservers stack — ten services in total: three PostgreSQL databases, one Redis instance, four microservices (auth, catalog, cart, orders), one Nginx gateway, and the Next.js frontend. Docker Compose handles build contexts, environment variable injection, dependency ordering, health checks, networking, and persistent data volumes, so a single command brings the full platform online from a clean machine.

​
Common Commands

The commands below cover the full lifecycle of the stack. Run them from the project root where docker-compose.yml lives. 
# Start everything (with build)
docker compose up --build

# Start in detached mode (runs in the background)
docker compose up --build -d

# Rebuild a single service without restarting the rest
docker compose up --build auth   # or: catalog | cart | orders | frontend

# Stop all containers and remove them (volumes are preserved)
docker compose down

# Stop all containers, remove them, and wipe all named volumes (resets every database)
docker compose down -v

# Stream logs for a specific service
docker compose logs -f orders
The first docker compose up --build will pull base images, install dependencies, and run Prisma migrations inside each service container — this can take a few minutes. Subsequent starts are much faster because Docker caches the image layers.

​
Services

The table below lists every service defined in docker-compose.yml along with its build source or image, any host-exposed port, and its role in the stack.
ServiceBuild / ImageExposed PortPurpose
catalog_dbpostgres:16-alpine—PostgreSQL instance for the catalog microservice
auth_dbpostgres:16-alpine—PostgreSQL instance for the auth microservice
orders_dbpostgres:16-alpine—PostgreSQL instance for the orders microservice
redisredis:7-alpine—Redis instance for ephemeral cart storage
auth./services/auth—Authentication microservice (port 3004 internally)
catalog./services/catalog—Product catalog microservice (port 3001 internally)
cart./services/cart—Shopping cart microservice (port 3002 internally)
orders./services/orders—Order processing microservice (port 3003 internally)
frontend./frontend—Next.js 15 frontend (port 3000 internally)
gateway./gateway${GATEWAY_PORT:-80}:80Nginx reverse proxy — the only publicly reachable entry point
Only the gateway service binds a host port. All other services communicate exclusively over the internal shop Docker network using service names as hostnames (e.g., http://catalog:3001). This means none of the microservices or databases are directly reachable from outside the Docker environment.

​
Health Checks

Every service in the stack declares a healthcheck so Docker Compose can enforce a safe startup order. This prevents a microservice from starting before its database is ready to accept connections, and prevents the gateway from routing traffic before all four microservices are healthy.

PostgreSQL (pg_isready)

Each Postgres container runs pg_isready -U <user> -d <database> every 10 seconds with a 5-second timeout and up to 5 retries before being marked unhealthy.

Redis (redis-cli ping)

The Redis container runs redis-cli ping every 10 seconds with a 5-second timeout and up to 5 retries.

Microservices (wget /health)

Each microservice hits its own GET /health endpoint via wget every 15 seconds with a 5-second timeout and up to 5 retries. All four services expose this endpoint.

Gateway (wget /health)

The Nginx gateway hits GET /health on itself every 15 seconds with a 5-second timeout and up to 5 retries. It only starts after all four microservices pass their own health checks.

Frontend (wget localhost:3000)

The Next.js frontend fetches http://localhost:3000 every 20 seconds with a 10-second timeout and up to 5 retries. The longer interval and timeout account for Next.js server startup time.

​
Networks

All services are attached to a single Docker bridge network named shop, declared at the top of docker-compose.yml: 
networks:
  shop:
    driver: bridge
Inside this network, every service is reachable at its Compose service name as a hostname — for example, the orders service calls the catalog service at http://catalog:3001 and the cart service at http://cart:3002. No extra DNS configuration is needed. Because only the gateway service publishes a host port, the shop network is effectively private: external traffic must flow through Nginx, which proxies requests to the appropriate microservice based on the URL path.

​
Volumes

Four named volumes persist data across container restarts: 
volumes:
  catalog_db_data:
  auth_db_data:
  orders_db_data:
  redis_data:
VolumeUsed ByContents
catalog_db_datacatalog_dbCatalog PostgreSQL data directory (Product table)
auth_db_dataauth_dbAuth PostgreSQL data directory (User table)
orders_db_dataorders_dbOrders PostgreSQL data directory (Order, OrderItem tables)
redis_dataredisRedis append-only file (cart data, 7-day TTL per key)
Running docker compose down -v deletes all four volumes and permanently erases every database and cache entry. Use this command to reset the stack to a clean state during development, but never run it against a production environment with real data.

​
Startup Order

Docker Compose respects depends_on conditions to boot services in the correct sequence. No service starts until its declared dependencies are healthy.
1

Databases and Redis start first

catalog_db, auth_db, orders_db, and redis boot in parallel. Each runs its health check until it reports healthy before downstream services are allowed to start.
2

Microservices start next

Once their respective backing stores are healthy, auth, catalog, cart, and orders each build, run Prisma migrations, and begin serving traffic on their internal ports. auth waits for auth_db, catalog waits for catalog_db, cart waits for redis, and orders waits for orders_db, catalog, and cart to all be healthy before it starts.
3

Gateway starts after all microservices are healthy

The gateway service has depends_on conditions requiring auth, catalog, cart, and orders to all pass their health checks. Only then does Nginx load its configuration and begin accepting inbound connections on GATEWAY_PORT.
4

Frontend starts last

The frontend service declares a dependency on gateway, ensuring the Next.js application only starts once the full backend is reachable. The frontend is served internally on port 3000 and proxied through the gateway at the / path.
If a service gets stuck in a restart loop during first boot (common while Postgres is initializing), Docker Compose’s health check retries will eventually resolve it without any manual intervention. You can monitor progress in real time with docker compose logs -f.

Build docs developers (and LLMs) love

Get started for freeTalk to us