Run MongoDB with Docker Compose

[ebouchut]

Goal

Add MongoDB to the local development environment as a containerized service named learn-dev-mongo in docker-compose.yaml, so the application can persist document-oriented data alongside PostgreSQL.

Rationale

The platform already uses PostgreSQL for relational data (users, roles, audit logs). MongoDB is being introduced to store document-oriented data such as course content (lessons, exercises, rich markdown blocks), submissions, or activity logs, where a flexible schema better fits the use case than a relational model.

This work also contributes to DWWM Competence 1: Installer et configurer son environnement de travail, specifically the criterion "Les conteneurs implémentent les services requis pour l'environnement de développement".

Scope

• Add a learn-dev-mongo service to docker-compose.yaml.
• Pin an explicit MongoDB image version.
• Persist data in a named Docker volume.
• Wire credentials through environment variables loaded from .env.
• Add a healthcheck.
• Update README.md with usage instructions.

Target Architecture

flowchart LR
    App[Spring Boot App] -->|JDBC| PG[(learn-dev-postgres)]
    App -->|Mongo Driver| MG[(learn-dev-mongo)]
    PG --- VP[(postgres_data volume)]
    MG --- VM[(mongo data volume)]

Loading

Service Specification

The new service must satisfy the following:

• Service name: learn-dev-mongo
• Container name: learn-dev-mongo
• Image: mongo:8.0 (latest stable major; pin to the minor version, not latest)
• Restart policy: unless-stopped
• Host port: 27017 mapped to container 27017
• Named volume: mongo_data mounted at /data/db
• Init scripts volume (optional): ./docker/mongo/init:/docker-entrypoint-initdb.d:ro
• Network: shared learn-dev-net network with the rest of the stack
• Credentials sourced from .env (never hard-coded)
• Healthcheck using mongosh ping

Add a service to docker-compose.yaml

services:
  mongo:
    image: mongo:8.0
    restart: unless-stopped
    ports:
      - "${MONGO_HOST}${MONGO_HOST:+:}${MONGO_PORT:-27017}:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGO_ROOT_USERNAME}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD}
      MONGO_INITDB_DATABASE:      ${LEARNDEV_MONGO_DB_NAME:-learndev}
    volumes:
      - mongo_data:/data/db
      - ./docker/mongo/init:/docker-entrypoint-initdb.d:ro
    networks:
      - learn-dev-net
    healthcheck:
      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

volumes:
  mongo_data:

networks:
  learn-dev-net:
    driver: bridge

Environment Variables

Add the following entries to .env.example (committed) and .env (git-ignored):

# MongoDB
MONGO_HOST=127.0.0.1
MONGO_PORT=27018
MONGO_ROOT_USERNAME=learndev_admin
MONGO_ROOT_PASSWORD=change_me_locally
LEARNDEV_MONGO_DB_NAME=learndev

Apple Silicon Note

MongoDB 8.x ships official linux/arm64 images, so the service runs natively on the MacBook Pro M1. No platform: override is required. If a regression appears, fall back to platform: linux/amd64 as a temporary workaround and document the reason.

Tasks

• Update docker-compose.yaml with the learn-dev-mongo service, mongo_data volume, and learn-dev-net network.
• Create docker/mongo/init/ directory with a placeholder .gitkeep.
• Add MongoDB variables to .env.example.
• Verify that .env is in .gitignore.
• Add a README.md section "Running MongoDB locally" covering start, stop, logs, shell access, and reset.
• Add a make target or shell alias (optional) such as mongo-shell for docker exec -it learn-dev-mongo mongosh.
• Validate that docker compose up -d learn-dev-mongo brings the service to a healthy state.
• Connect from the host with mongosh to confirm credentials work.

Acceptance Criteria

The issue is considered done when all of the following are true:

• Running docker compose up -d learn-dev-mongo from a clean checkout starts the service successfully.
• docker compose ps reports the service as healthy within 30 seconds.
• A mongosh session from the host authenticates using the credentials in .env.
• Stopping and restarting the container preserves data via the mongo_data volume.
• No credentials are committed to the repository.
• README.md documents the start, stop, and reset procedures.

Security Considerations

• Authentication is enabled by default through MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD.
• Secrets are loaded from .env and must remain git-ignored.
  The repository only ships .env.example.
• Add a follow-up issue to track integration with 1Password CLI for local secret management.

Definition of Done

Code merged to dev via a pull request that:

• Includes an updated README.md and .env.example.
• Links back to this issue with Closes #<issue-number>.
• Update Dossier Professionnel Compétence 1: Installer et configurer son environnement de travail en fonction du projet web ou web mobile

Resources

References

• MongoDB Docker image: https://hub.docker.com/_/mongo
• Compose specification: https://github.com/compose-spec/compose-spec/blob/main/spec.md

Thanks to my 🤖-C-budy for the write-up and the advices.

[ebouchut]

Closed by #26