Deployment Guide

Relevant source files

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

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

This guide provides instructions for deploying the MessageJS backend services for a development environment. MessageJS is a monorepo containing multiple packages, including the core API (@messagejs/core), a client SDK (@messagejs/client), and a dashboard. This document focuses on setting up the @messagejs/core service and its PostgreSQL database dependency.

The high-level architecture involves a client-side SDK that communicates with the backend API, which in turn relies on a PostgreSQL database for persistence and Redis for caching.

Sources: README.md:16-22, mono-repo.md

1. Prerequisites

Before starting, ensure the following tools are installed on your system:

Tool	Required Version	Source
Node.js	>=20.0.0	package.json:20
npm	>=10.0.0	package.json:21
Docker	-	docker-compose.yml
Docker Compose	-	docker-compose.yml

Sources: package.json:19-22, docker-compose.yml:1-10

2. System Architecture

The MessageJS system is composed of several key components that interact to deliver messages.

This diagram shows the flow where a user's application uses the Client SDK to send a request to the Core API. The API processes the request, logs it to the PostgreSQL database, and forwards it to the appropriate third-party messaging service.

Sources: README.md:46-52

3. Deployment Steps

The following steps outline the process for setting up the development environment.

Step 1: Clone Repository & Install Dependencies

First, clone the repository and install the dependencies for all packages in the monorepo.

# Clone the repository
git clone https://github.com/messagejs/messagejs.git
cd messagejs

# Install dependencies for all workspaces
npm install

Sources: README.md:26-30

Step 2: Start the Database

The development environment uses Docker Compose to run a PostgreSQL database.

1. Navigate to the root of the project.

2. Run the following command to start the database service in the background:

   docker-compose up -d
   

This command provisions a PostgreSQL 15 container. The database will be accessible on localhost:5432.

Sources: docker-compose.yml:8-10, 16-17

Database Configuration

The docker-compose.yml file defines the configuration for the PostgreSQL service.

Service	Image	Container Name	Port Mapping
postgres	postgres:15-alpine	messagejs_postgres_dev	5432:5432

Sources: docker-compose.yml:13-17, 28-29

The following environment variables are used to configure the database instance. These credentials must be used to construct the DATABASE_URL for the core service.

Variable	Value	Description
POSTGRES_USER	messagejs	The username for the database.
POSTGRES_PASSWORD	password	The password for the database user.
POSTGRES_DB	messagejs_dev	The name of the database.

Sources: docker-compose.yml:21-23

Step 3: Configure the Core API

The @messagejs/core service requires a .env file for its configuration.

1. Create a file named .env inside the packages/core/ directory.

2. Add the following environment variables:

   # Connection URL for the PostgreSQL database started with Docker Compose.
   # Format: postgresql://<USER>:<PASSWORD>@<HOST>:<PORT>/<DATABASE>
   DATABASE_URL="postgresql://messagejs:password@localhost:5432/messagejs_dev"
   
   # Optional: Port for the backend server to run on. Defaults to 3001.
   PORT=3001
   

Sources: packages/core/src/index.ts:13-14, packages/core/prisma/schema.prisma:9-10, docker-compose.yml:21-23

Step 4: Run Database Migrations

MessageJS uses Prisma as its ORM. The database schema is defined in packages/core/prisma/schema.prisma. Before running the application, you must apply the database migrations to create the necessary tables.

The migration.sql file shows the tables that will be created, including User, Project, Service, Template, and MessageLog.

Sources: packages/core/prisma/migrations/20251029214807_init/migration.sql

Database Schema (ER Diagram)

The following diagram illustrates the relationships between the database models as defined in the Prisma schema.

To apply migrations, run the Prisma command (Note: the specific command prisma migrate dev is standard practice but not explicitly in the scripts; its necessity is implied by the use of Prisma and the presence of a migration file).

Step 5: Start the Services

The root package.json provides scripts to run the different packages. To start the backend API in development mode (with hot-reloading), run:

# Starts the core backend on http://localhost:3001 (or your configured PORT)
npm run core

This command executes the dev script within the @messagejs/core workspace.

Sources: package.json:13, packages/core/package.json:10

You can verify the service is running by accessing the health check endpoint at http://localhost:3001. It should return a JSON response with status: 'ok'.

Sources: packages/core/src/index.ts:24-29