Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/whitiue/logiMathApp/llms.txt

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

Docker Compose is the recommended way to run LogiMath locally and in team environments. A single docker-compose.yml file at the project root orchestrates two services — the FastAPI backend and a PostgreSQL 16 database — on a shared internal network, with healthchecks ensuring the database is ready before the backend starts.

​
Compose file overview

The full docker-compose.yml defines both services, a named volume for persistent database storage, and a bridge network so containers can reach each other by service name:
docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: logmath_db
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/init.sql:/docker-entrypoint-initdb.d/01-init.sql
    networks:
      - logmath_network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
    restart: unless-stopped

  backend:
    build:
      context: ./
      dockerfile: ./src/BackEnd/Dockerfile
    container_name: logmath_backend
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - API_HOST=${API_HOST}
      - API_PORT=${API_PORT}
    networks:
      - logmath_network
    healthcheck:
      test: ["CMD-SHELL", "python -c 'import urllib.request; urllib.request.urlopen(\"http://localhost:8000/\").read()'"]
      interval: 30s
      timeout: 10s
      retries: 3
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M
    restart: unless-stopped

networks:
  logmath_network:
    driver: bridge

volumes:
  postgres_data:
    driver: local
Key things to note:
  • Healthchecks: The postgres service uses pg_isready to verify the database accepts connections. The backend service uses a Python one-liner to hit http://localhost:8000/. The backend’s depends_on condition waits for postgres to pass its healthcheck before starting.
  • Resource limits: PostgreSQL is capped at 0.5 CPU / 512 MB RAM; the backend at 1 CPU / 1 GB RAM. These prevent runaway containers on developer machines.
  • Database initialization: The file ./docker/init.sql is mounted into the PostgreSQL initialization directory and runs automatically the first time the container starts.
  • Persistent storage: The postgres_data named volume survives container restarts, so your data is not lost when you run docker-compose down.

​
Build and start the services

Before running, copy .env.example to .env and fill in your credentials. See Environment variables for details.
1

Set up your environment file

Copy the example environment file and update the values for your local setup:
cp .env.example .env
Open .env and replace the placeholder password with a real one before proceeding.
2

Build the Docker images

Build the backend image from ./src/BackEnd/Dockerfile:
docker-compose build
Docker downloads the postgres:16-alpine base image and builds the Python 3.12 backend image. This step only needs to run again if you change requirements.txt or the Dockerfile.
3

Start all services

Start both containers in the foreground so you can see logs from both services:
docker-compose up --build
Docker Compose waits for the postgres healthcheck to pass before launching the backend. Once the backend is ready, the API is available at http://localhost:8000.
Pass -d to run in detached (background) mode: docker-compose up --build -d
4

Verify the services are running

In a separate terminal, check that both containers are up and healthy:
docker-compose ps
Both logmath_db and logmath_backend should show a running or healthy status.
5

Inspect logs

View streaming logs from all services, or scope to one:
# All services
docker-compose logs

# Backend only
docker-compose logs backend

# PostgreSQL only
docker-compose logs postgres
6

Stop the services

Stop and remove the containers when you’re done:
docker-compose down
Your database data is preserved in the postgres_data volume. To remove the volume as well (this deletes all data), run:
docker-compose down -v
Running docker-compose down -v permanently deletes the postgres_data volume and all data stored in it.

​
Database initialization

On first startup, PostgreSQL automatically executes ./docker/init.sql because it is mounted at /docker-entrypoint-initdb.d/01-init.sql. This file runs once and is skipped on subsequent starts if the data volume already exists. Use this file to create schemas, seed reference data, or set up roles required by the application.
The initialization script only runs when the postgres_data volume is empty. To re-run it, remove the volume with docker-compose down -v and start fresh.

Build docs developers (and LLMs) love

Get started for freeTalk to us