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.

Each Shop Microservers service is fully self-contained — it has its own package.json, TypeScript config, and database schema. This means you can run any single service in isolation using tsx watch for file-watching hot reload, without spinning up the entire Docker Compose stack. This is the recommended workflow when you are actively extending or debugging a service, as it gives you instant feedback and direct access to logs without container overhead.

​
Prerequisites

Node.js 20+

All services require Node.js 20 or later. Use node -v to confirm your version.

npm

Each service manages its own node_modules. Run npm install inside the service directory before starting.

PostgreSQL instance

Auth, catalog, and orders each require a running Postgres 16 database reachable via DATABASE_URL.

Redis instance

The cart service requires a running Redis 7 instance reachable via REDIS_URL.
You don’t have to run Postgres or Redis natively. You can start only the database containers from the Compose file while developing the service directly on your machine:
# Start only the catalog database container
docker compose up catalog_db -d

# Start only the orders/auth database container
docker compose up orders_db -d

# Start only Redis for the cart service
docker compose up redis -d
This keeps infrastructure isolated in Docker while your service code runs with native hot reload.

​
Available Scripts

Every service shares the same script conventions in its package.json. The scripts available depend on whether the service has a database.
ScriptCommandServices
npm run devtsx watch src/index.tsAll four services
npm run buildtscAll four services
npm run db:pushprisma db pushauth, catalog, orders
npm run db:generateprisma generateauth, catalog, orders
npm run db:seedtsx prisma/seed.tscatalog only
The cart service has no database scripts because it uses Redis exclusively — no Prisma, no migrations, no seed.

​
Service Ports and Environment Variables

Each service listens on a fixed default port and reads its configuration from environment variables. Set these before running npm run dev.
ServiceDefault PortKey Environment Variables
auth3004DATABASE_URL, JWT_SECRET
catalog3001DATABASE_URL
cart3002REDIS_URL, JWT_SECRET
orders3003DATABASE_URL, CATALOG_URL, CART_URL, JWT_SECRET
frontend3000NEXT_PUBLIC_API_URL

​
Walkthrough: Running the Catalog Service

The catalog service is a good starting point because it is stateless beyond its database and does not call any other service.
1

Navigate to the service directory

cd services/catalog
2

Install dependencies

npm install
3

Point DATABASE_URL at a running Postgres instance

The default credentials match the Docker Compose setup. Adjust the host, port, or credentials if your local Postgres differs.
export DATABASE_URL="postgresql://shop:shop@localhost:5432/catalog"
4

Apply the schema and seed the database

npm run db:push
npm run db:seed
db:push applies the Prisma schema directly to the database. db:seed inserts 12 sample products — it is idempotent and will skip insertion if products already exist.
5

Start the service with hot reload

npm run dev
The catalog service is now running at http://localhost:3001. File changes in src/ trigger an automatic restart via tsx watch.

​
Walkthrough: Running the Cart Service

The cart service is the simplest to run locally because it has no Prisma schema or migrations — only a Redis connection and a JWT secret.
1

Navigate to the service directory

cd services/cart
2

Install dependencies

npm install
3

Set the required environment variables

export REDIS_URL="redis://localhost:6379"
export JWT_SECRET="your-secret"
JWT_SECRET must match the value used by the auth service so that tokens issued by auth can be verified by cart.
4

Start the service with hot reload

npm run dev
The cart service is now running at http://localhost:3002 and will accept requests with a valid Authorization: Bearer <token> header.
When running services locally, inter-service calls from the orders service (to http://catalog:3001 and http://cart:3002) will fail because Docker’s internal DNS is not available outside of Docker Compose. Override CATALOG_URL and CART_URL to point to your local ports:
export CATALOG_URL="http://localhost:3001"
export CART_URL="http://localhost:3002"

Build docs developers (and LLMs) love

Get started for freeTalk to us