Using Docker Compose

Relevant source files

The following files were used as context for generating this wiki page:

• docker-compose.yml
• packages/core/prisma/schema.prisma
• packages/core/src/index.ts
• README.md
• QUICK_START.md
• packages/core/package.json

The MessageJS project utilizes Docker Compose to define and run a multi-container Docker application for the development environment. The primary purpose of this setup is to provide a consistent and isolated PostgreSQL database instance, which is a core dependency for the @messagejs/core backend service. This approach simplifies the setup process for developers, ensuring that the required database is running with the correct configuration without needing a manual installation on the host machine.

The configuration is defined in the docker-compose.yml file at the root of the project. It orchestrates the postgres service, manages its configuration, networking, and data persistence.

Sources: docker-compose.yml, README.md:50-54

Architecture Overview

The Docker Compose setup creates a postgres service that the @messagejs/core Node.js application connects to. The application itself runs on the host machine during development, not within a Docker container defined in this file.

The following diagram illustrates the development environment architecture:

This diagram shows the @messagejs/core application running on the host, connecting to the PostgreSQL container managed by Docker. The container's data is persisted in a local Docker volume.

Sources: docker-compose.yml:15-39, packages/core/prisma/schema.prisma:8-9, packages/core/src/index.ts:1-20

Services

The docker-compose.yml file defines a single service for the development environment.

Sources: docker-compose.yml:15

PostgreSQL Service (postgres)

This service is responsible for running the PostgreSQL database. The @messagejs/core backend uses this database for all its data persistence needs, as defined by the Prisma schema.

Sources: docker-compose.yml:17, packages/core/prisma/schema.prisma

The service is configured with the following parameters:

Parameter	Value	Description
image	postgres:15-alpine	Specifies the official PostgreSQL version 15 image with an Alpine Linux base for a smaller size.
container_name	messagejs_postgres_dev	A custom, predictable name for the container.
environment	See table below	Sets the database user, password, and name.
ports	- "5432:5432"	Maps port 5432 of the container to port 5432 on the host machine, allowing the Node.js app to connect.
volumes	- postgres_data:/var/lib/postgresql/data	Mounts a named volume to persist database data.
restart	always	Ensures the container restarts automatically if it stops.

Sources: docker-compose.yml:17-36

Below is the YAML configuration for the postgres service:

services:
  # Defines the PostgreSQL database service.
  postgres:
    # Use the official PostgreSQL image, specifying a version for consistency.
    # The 'alpine' tag is used for a smaller image size.
    image: postgres:15-alpine
    container_name: messagejs_postgres_dev

    # Environment variables to configure the PostgreSQL instance.
    # These MUST match the credentials in `packages/core/.env`.
    environment:
      POSTGRES_USER: messagejs
      POSTGRES_PASSWORD: password
      POSTGRES_DB: messagejs_dev

    # Maps port 5432 of the container to port 5432 on the host machine.
    # This allows our Node.js application (running on the host) to connect to the database.
    ports:
      - "5432:5432"

    # Defines a volume to persist the database data.
    # This ensures that your data is not lost when the container is stopped or removed.
    volumes:
      - postgres_data:/var/lib/postgresql/data

    # Restart policy: ensures the container will restart automatically if it stops.
    restart: always

Sources: docker-compose.yml:15-36

Configuration and Environment

The environment variables set within docker-compose.yml are crucial for initializing the PostgreSQL container.

Variable	Value	Description
POSTGRES_USER	messagejs	The username for the PostgreSQL database.
POSTGRES_PASSWORD	password	The password for the specified user.
POSTGRES_DB	messagejs_dev	The name of the database to be created on initialization.

These values must be used to construct the DATABASE_URL in the .env file for the @messagejs/core package, which Prisma uses to connect to the database. The expected format is postgresql://messagejs:password@localhost:5432/messagejs_dev.

Sources: docker-compose.yml:23-26, packages/core/prisma/schema.prisma:8-9

Data Persistence

To prevent data loss when the container is stopped or removed, the configuration defines a named volume called postgres_data.

volumes:
  postgres_data:
    driver: local

This top-level volumes key declares the named volume, and the volumes key within the postgres service definition maps the container's internal data directory (/var/lib/postgresql/data) to this named volume. This ensures that all database files are stored on the host machine's Docker-managed storage area.

Sources: docker-compose.yml:33-34, docker-compose.yml:38-40

Usage and Commands

The docker-compose.yml file includes comments that guide developers on how to manage the services.

Developer Workflow

The typical workflow for using the Docker Compose environment is as follows:

Commands

• Start Services: To start the PostgreSQL container in the background (detached mode), run the following command from the project root:

  docker-compose up -d
  

  Sources: docker-compose.yml:8

• Stop Services: To stop and remove the container, run:

  docker-compose down
  

  This command will stop the container but will not delete the postgres_data volume, preserving your database state for the next session.
  Sources: docker-compose.yml:11

Summary

The Docker Compose setup for MessageJS provides a streamlined and reproducible way to run the necessary PostgreSQL database for local development. It decouples the database dependency from the host machine, ensures consistent configuration across the team, and simplifies the process of starting and stopping the development environment. This is a foundational element for working on the @messagejs/core API.

Sources: docker-compose.yml, QUICK_START.md