All configuration in Shop Microservers is driven by environment variables. At startup, Docker Compose reads aDocumentation 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.
.env file from the project root and injects the relevant variables into each container — no service reads .env directly at runtime. This means a single file controls every aspect of the stack: database credentials, JWT signing, the public gateway port, and the URL the frontend uses to reach the API.
Getting Started
Before running the stack for the first time, copy the example file and fill in your values:Review the defaults
The example ships with safe placeholder values so the stack starts without any changes. Open
.env and, at minimum, set a strong JWT_SECRET before exposing the application publicly.Variable Reference
Database
These four variables are shared across all three PostgreSQL instances (catalog_db, auth_db, orders_db). Docker Compose interpolates them into each container’s POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB environment variables, as well as the DATABASE_URL connection strings passed to each microservice.
Shared PostgreSQL username created in every database instance on first boot. All three Postgres containers and all Prisma connection strings use this same user.
Shared PostgreSQL password for
POSTGRES_USER. The default value shop is intentionally weak — change this before any public deployment.Name of the database created inside the
catalog_db Postgres container. The catalog microservice’s DATABASE_URL is constructed from this value.Name of the database created inside the
orders_db Postgres container. The orders microservice’s DATABASE_URL is constructed from this value.Authentication
Secret key used to sign and verify JSON Web Tokens across all services that need authentication —
auth, cart, and orders all read this value. There is no safe built-in default; if left empty the auth service will start but token operations will fail unpredictably. Tokens issued by the auth service carry a 7-day expiry. Rotate this secret to immediately invalidate all active sessions.Gateway
The host port mapped to the Nginx gateway container’s internal port 80. Change this if port 80 is already in use on your machine (e.g.,
GATEWAY_PORT=8080). In production, set this to 443 and add TLS termination in front of Nginx.Frontend
Base URL the Next.js frontend uses to build API request paths. Because it is prefixed with
NEXT_PUBLIC_, it is embedded into the browser bundle at build time. When GATEWAY_PORT is not 80, update this to http://localhost:${GATEWAY_PORT}. In production, set this to your real domain (e.g., https://shop.example.com).Service-Internal Variables
The following variables are set directly insidedocker-compose.yml and are not part of .env.example. They are documented here for completeness when developing or debugging individual services outside of Docker.
You do not need to set these manually when using
docker compose up. They are injected automatically and are only relevant if you run a service with npm run dev outside of Docker.| Variable | Service(s) | Value | Purpose |
|---|---|---|---|
PORT | auth | 3004 | Internal HTTP port the service listens on |
PORT | catalog | 3001 | Internal HTTP port the service listens on |
PORT | cart | 3002 | Internal HTTP port the service listens on |
PORT | orders | 3003 | Internal HTTP port the service listens on |
AUTH_DB_NAME | auth_db | auth | Name of the database created inside the auth_db Postgres container. Defaults to auth when not set in .env. |
DATABASE_URL | auth | postgresql://<user>:<pass>@auth_db:5432/${AUTH_DB_NAME:-auth} | Full Prisma connection string for the auth database |
DATABASE_URL | catalog | postgresql://<user>:<pass>@catalog_db:5432/${CATALOG_DB_NAME:-catalog} | Full Prisma connection string for the catalog database |
DATABASE_URL | orders | postgresql://<user>:<pass>@orders_db:5432/${ORDERS_DB_NAME:-orders} | Full Prisma connection string for the orders database |
REDIS_URL | cart | redis://redis:6379 | Redis connection string for cart storage |
CATALOG_URL | orders | http://catalog:3001 | URL the orders service uses to verify and decrement stock via the catalog service |
CART_URL | orders | http://cart:3002 | URL the orders service uses to clear the user’s cart after a successful checkout |
shop bridge network.