Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bentlyy/Clinica/llms.txt

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

Docker Compose is the fastest way to run the entire Clinica stack on your machine. A single command builds and starts all three services — the Node.js API, the React frontend, and the PostgreSQL database — with no manual configuration required.

​
Services

Clinica’s docker-compose.yml defines three services:
ServiceImage / BuildPortDescription
api./dockerfile3000Node.js REST API (Express)
frontend./frontend/Dockerfile5173React app served by Vite
dbpostgres:15—PostgreSQL 15 database
The frontend service depends on api, and api depends on db. Docker Compose starts services in dependency order automatically.

​
docker-compose.yml

docker-compose.yml
version: '3.8'

services:
  api:
    build: .
    command: npm run dev
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      - db

  frontend:
    build: ./frontend
    volumes:
      - ./frontend:/app
      - /app/node_modules
    ports:
      - "5173:5173"
    environment:
      - CHOKIDAR_USEPOLLING=true
    depends_on:
      - api

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: clinic
    volumes:
      - ./db/init.sql:/docker-entrypoint-initdb.d/init.sql
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

​
Starting the stack

1

Clone the repository

If you haven’t already, clone the Clinica repository and navigate into it.
git clone https://github.com/bentlyy/Clinica.git
cd Clinica
2

Configure environment variables

The repository ships with a .env file containing working defaults for Docker Compose. Open it and update jwt_secret and the email credentials before starting.
# Edit .env directly — Docker Compose reads this file via env_file
nano .env
See the environment variables reference for all available options.
3

Build and start all services

Run the following command from the repository root. The --build flag rebuilds images when source files have changed.
docker compose up --build
On first run, Docker pulls the postgres:15 image, builds the api and frontend images, and initialises the database schema. This takes a minute or two.
4

Verify the services are running

Once all containers are healthy, open the following URLs in your browser:

​
Database initialisation

When the db container starts for the first time, PostgreSQL automatically runs every SQL file mounted into /docker-entrypoint-initdb.d/. Clinica mounts db/init.sql at that path, which creates the following tables:
TablePurpose
usersAuthentication accounts with roles
doctorsDoctor profiles linked to user accounts
bookingsAppointment records with reminder tracking
doctor_availabilityWeekly availability windows per doctor
doctor_exceptionsOne-off blocked dates or time ranges
The init script runs only once — when the db_data volume is first created. If you change db/init.sql after the volume already exists, you need to reset the database for the changes to take effect.

​
Volumes

VolumeMounted atPurpose
db_data/var/lib/postgresql/dataPersists PostgreSQL data across restarts
. (bind)/app (api container)Live-reloads API source changes
./frontend (bind)/app (frontend container)Live-reloads frontend source changes
The db_data named volume ensures your data survives docker compose down. Only docker compose down -v removes it.

​
Port mappings

Host portContainer portService
30003000api
51735173frontend
The db service does not expose a host port by default. The API connects to it over the internal Docker network using the hostname db.

​
Health check

The API exposes a health check endpoint. Use it to confirm the service is reachable before sending other requests. 
curl http://localhost:3000/health
A successful response indicates the API container is running and accepting connections.

​
Stopping the stack

To stop all containers without removing data: 
docker compose down

​
Resetting the database

To stop all containers and delete all persisted data (including the db_data volume): 
docker compose down -v
docker compose down -v permanently deletes all database content. The next docker compose up will re-run db/init.sql and start with an empty database.

Build docs developers (and LLMs) love

Get started for freeTalk to us