Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/joaomonteir0/printheritage/llms.txt

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

The docker-compose.yml at the root of the PrintHeritage repository orchestrates three cooperating services — a PostgreSQL 15 database, a FastAPI authentication backend, and a React front-end — on a shared Docker network. This page documents every service definition, explains the port mappings and volume mounts, and provides the common commands needed to operate the stack locally and in CI.

​
Architecture Overview

db-auth

PostgreSQL 15 (Alpine). Stores user accounts and project permissions. Accessible only within the Docker network in production; port 5432 is forwarded to the host for local development convenience.

auth-service

FastAPI application served by Uvicorn on internal port 8000, mapped to host port 8001. Handles registration, login, JWT issuance, and role-based access control.

front-end

Create React App development server on port 3000. Communicates exclusively with auth-service via REACT_APP_API_URL. Source files are hot-reloaded through a bind mount.
The start-up dependency chain is: db-auth → auth-service → front-end. Docker Compose enforces this ordering via depends_on, though it does not wait for a service to be healthy — only for its container to start. The auth service therefore implements its own retry loop (up to 5 retries, 3-second delay) when connecting to PostgreSQL.

​
Full docker-compose.yml

services:
  db-auth:
    image: postgres:15-alpine
    container_name: auth-db-postgres
    restart: always
    environment:
      POSTGRES_USER: auth_user
      POSTGRES_PASSWORD: auth_password
      POSTGRES_DB: auth_db
    ports:
      - "5432:5432"
    volumes:
      - auth_db_data:/var/lib/postgresql/data

  auth-service:
    build: ./auth-service
    container_name: auth-service-api
    restart: always
    environment:
      - DATABASE_URL=postgresql://auth_user:auth_password@db-auth:5432/auth_db
      - SECRET_KEY=CHAVE_MUITO_SECRETA_PARA_PRODUCAO
    ports:
      - "8001:8000"
    depends_on:
      - db-auth
    volumes:
      - ./auth-service:/app

  front-end:
    build: ./front-end
    container_name: front-end-react
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - ./front-end/src:/app/src
    depends_on:
      - auth-service
    environment:
      - REACT_APP_API_URL=http://localhost:8001

volumes:
  auth_db_data:

​
Service Reference

​
db-auth

The db-auth service provides the persistent relational store for all authentication data.
PropertyValue
Imagepostgres:15-alpine
Container nameauth-db-postgres
Restart policyalways
Host → container port5432 → 5432
Volumeauth_db_data:/var/lib/postgresql/data (named volume)
The three POSTGRES_* environment variables seed the database on first run. Once the auth_db_data volume exists these values are ignored by PostgreSQL itself — the data directory is already initialised. To apply new credentials to an existing installation you must alter them inside the running database and then update docker-compose.yml to match.
The named volume auth_db_data is declared at the top level of docker-compose.yml under volumes:. Docker Compose creates it automatically the first time the stack is brought up. Removing it with docker compose down -v permanently deletes all stored user data.

​
auth-service

The auth-service is the Python backend, built from ./auth-service/Dockerfile which uses python:3.11-slim as its base image.
PropertyValue
Build context./auth-service
Container nameauth-service-api
Restart policyalways
Host → container port8001 → 8000
Depends ondb-auth
Bind mount./auth-service:/app
Port mapping detail: Uvicorn inside the container listens on port 8000 (as declared by EXPOSE 8000 and CMD uvicorn main:app --port 8000 in the Dockerfile). Docker maps this to host port 8001 so the API is reachable at http://localhost:8001 without conflicting with any other service that might occupy port 8000 on the host. The bind mount ./auth-service:/app overlays the entire source directory onto the container’s working directory. This means any Python file edit on the host is immediately reflected inside the container, enabling Uvicorn’s auto-reload in development without a rebuild.

​
front-end

The front-end service is a Create React App development server, built from ./front-end/Dockerfile using node:20-slim.
PropertyValue
Build context./front-end
Container namefront-end-react
Restart policyalways
Host → container port3000 → 3000
Depends onauth-service
Bind mount./front-end/src:/app/src
The Dockerfile sets ENV WDS_SOCKET_PORT=0 to resolve WebSocket HMR (Hot Module Replacement) connectivity issues that arise in some Docker networking environments.
The bind mount covers only the src/ subdirectory. Changes to package.json, package-lock.json, or Dockerfile itself are not reflected inside the running container. After modifying any of these files you must rebuild the image: docker compose up --build front-end.

​
Named Volumes

VolumeMounted inContainer pathPurpose
auth_db_datadb-auth/var/lib/postgresql/dataPersists the PostgreSQL data directory across container restarts and recreations. Without this volume, all user and permission data would be lost every time the db-auth container is stopped.

​
Common Commands

1

Start all services (with build)

Run this command from the repository root the first time you bring up the stack, or after any change to a Dockerfile or requirements.txt / package.json.
docker compose up --build
Logs from all three services stream to your terminal. Press Ctrl + C to stop.
2

Start detached (background)

Starts all services in the background and returns control to your shell immediately.
docker compose up -d --build
Use docker compose ps to confirm all containers are in the running state.
3

Stop all services

Stops and removes containers and the default network, but preserves the auth_db_data volume and your local source files.
docker compose down
4

Stop and remove all data

Stops containers and deletes all named volumes, including auth_db_data. All stored users and permissions are permanently erased. Use with caution.
docker compose down -v
5

Stream logs from auth-service

Follows live log output from the auth service container. Useful for debugging JWT errors, database connection retries, and API request traces.
docker compose logs -f auth-service
Replace auth-service with db-auth or front-end to tail logs from those services instead.

​
Dependency Graph

db-auth (postgres:15-alpine)
  └── auth-service (FastAPI / Uvicorn :8000 → host :8001)
        └── front-end (React CRA :3000 → host :3000)
Docker Compose starts services in this order and stops them in reverse order (front-end → auth-service → db-auth), ensuring clean disconnection at every layer.
During development you can restart a single service without touching the others. For example, after editing a Python route handler, run docker compose restart auth-service to pick up the change — the database and front-end keep running uninterrupted.

Build docs developers (and LLMs) love

Get started for freeTalk to us