Docker Deployment

Deploy the ReadRealm API and MongoDB database using Docker Compose for a self-contained, production-ready environment.

Docker Compose starts the NestJS API and a MongoDB 7.0 database together in an isolated network. This is the recommended way to run ReadRealm in production or for local development without installing MongoDB directly.

Prerequisites

• Docker Engine 24+
• Docker Compose v2+

Verify your installation:

docker --version
docker compose version

---

Setup

1. Clone the repository

   git clone https://github.com/aliammari1/readrealm.git
   cd readrealm
   
2. Configure environment variables

   Docker Compose reads credentials from your shell environment or a .env file at the project root. Set the required variables before starting services:

   export JWT_SECRET="your_jwt_secret_key_min_32_characters"
   export GOOGLE_AI_KEY="your_google_ai_api_key"
   export HUGGINGFACE_API_KEY="your_huggingface_api_key"
   export AZURE_TTS_KEY="your_azure_tts_key"
   export AZURE_REALTIME_KEY="your_azure_realtime_key"
   export MAIL_HOST="smtp.gmail.com"
   export MAIL_USER="[e-mail]"
   export MAIL_PASS="your_app_specific_password"
   

   Alternatively, create a .env file in the project root:

   .env

   JWT_SECRET=your_jwt_secret_key_min_32_characters
   GOOGLE_AI_KEY=your_google_ai_api_key
   HUGGINGFACE_API_KEY=your_huggingface_api_key
   AZURE_TTS_KEY=your_azure_tts_key
   AZURE_REALTIME_KEY=your_azure_realtime_key
   MAIL_HOST=smtp.gmail.com
   MAIL_USER=[e-mail]
   MAIL_PASS=your_app_specific_password
   

   Do not commit .env to version control. It is already listed in .gitignore.

   For a full description of each variable, see Environment Configuration.

3. Start services

   Docker Compose

   docker-compose up -d
   

   Task

   task docker:up
   

   Both services start in the background. The API is available at http://localhost:3000 once its health check passes.

4. Verify services are running

   docker-compose ps
   

   Both readrealm-api and readrealm-mongodb should show a healthy status. If the API container is still starting, wait a few seconds and check again — it waits for MongoDB to become healthy before accepting connections.

---

Services

The docker-compose.yaml defines two services:

version: '3.8'

services:
  api:
    build:
      context: ./apps/api
      dockerfile: Dockerfile
    container_name: readrealm-api
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
      MONGODB_URL: mongodb://mongodb:27017/readrealm
      JWT_SECRET: ${JWT_SECRET:-your_jwt_secret_key_here}
      GOOGLE_AI_KEY: ${GOOGLE_AI_KEY}
      HUGGINGFACE_API_KEY: ${HUGGINGFACE_API_KEY}
      AZURE_TTS_KEY: ${AZURE_TTS_KEY}
      AZURE_REALTIME_KEY: ${AZURE_REALTIME_KEY}
      MAIL_HOST: ${MAIL_HOST}
      MAIL_USER: ${MAIL_USER}
      MAIL_PASS: ${MAIL_PASS}
    depends_on:
      - mongodb
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5

  mongodb:
    image: mongo:7.0
    container_name: readrealm-mongodb
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db
      - mongodb_config:/data/configdb
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  mongodb_data:
  mongodb_config:

networks:
  readrealm-network:
    driver: bridge

Key points:

• The api service builds from apps/api/Dockerfile and exposes port 3000.
• The mongodb service uses the official mongo:7.0 image and persists data to named volumes (mongodb_data, mongodb_config).
• Both services restart automatically unless explicitly stopped.
• Health checks ensure MongoDB is ready before the API starts accepting traffic.

---

Common commands

Action	Docker Compose	Task
Start all services	docker-compose up -d	task docker:up
Stop all services	docker-compose down	task docker:down
View logs (all)	docker-compose logs -f	task docker:logs
View API logs only	docker-compose logs -f api	—
View MongoDB logs only	docker-compose logs -f mongodb	—
Rebuild and restart	docker-compose up -d --build	—
Remove volumes (reset DB)	docker-compose down -v	—

Running docker-compose down -v permanently deletes all stored data in MongoDB. Only use this when you want to start from a clean state.