Production Setup

Deploy OsmoX to a production environment

Production Setup

This document outlines the steps required to set up OsmoX for production. Following these steps will ensure that your application is configured properly for a production environment.

Prerequisites

Node.js v20.x+

Install via NVM

PostgreSQL v16.x+

Production database server

Redis v6.x+

Queue backend

PM2 v5.x+

Process manager for Node.js

Docker v26.1.2

Container runtime (optional)

Git v2.x+

Version control

Ensure Redis and PostgreSQL servers are running.

Environment Configuration

Create the .env file with production values:

cp .env.example .env

Update these critical production values:

Variable	Description
NODE_ENV	Set to production
SERVER_PORT	API server port
DB_HOST	PostgreSQL host
DB_PORT	PostgreSQL port
DB_USERNAME	Database username
DB_PASSWORD	Database password
REDIS_HOST	Redis host
REDIS_PORT	Redis port
API_KEY_SECRET	Secret for API key encryption
JWT_SECRET	Secret for JWT tokens

Build the Application

Before starting the server, build OsmoX:

npm run build

This compiles TypeScript code into JavaScript and generates the necessary build files.

Deployment Options

PM2

PM2 Deployment

1. Create PM2 Configuration

Create an ecosystem.config.js file:

module.exports = {
  apps: [
    {
      name: 'OsmoX',
      script: 'dist/main.js',
      instances: 1,
      autorestart: true,
      watch: false,
      max_memory_restart: '1G',
      env: {
        NODE_ENV: 'production',
      },
    },
  ],
};

2. Start with PM2

pm2 start ecosystem.config.js

3. Enable Auto-Start on Boot

pm2 startup

Follow any instructions provided by the command.

4. Save PM2 Configuration

pm2 save

Docker

Docker Deployment

Step 1: Configure Environment

Update your .env file with Docker-specific values:

• DB_HOST - Use the Docker service name
• REDIS_HOST - Use the Docker service name
• DB_DOCKER_PORT - Docker-exposed database port
• REDIS_DOCKER_PORT - Docker-exposed Redis port

Step 2: Build Docker Container

docker compose build

Step 3: Start Containers

docker compose up -d

Step 4: Run Migrations (First-Time Setup)

# Using container name
docker exec -it osmo-x-api-v2-osmox-api-1 npm run typeorm:run-migration

# OR using docker compose
docker exec -it $(docker compose ps -q osmox-api) npm run typeorm:run-migration

Updating Environment Variables

If you need to update environment variables in a Docker deployment:

1. Update .env file

   Modify the values in your .env file

2. Stop containers

   docker compose stop
   docker compose down -v
   
3. Rebuild containers

   docker compose build
   
4. Start containers

   docker compose up -d
   

Next Steps

Usage Guide

Learn how to make API calls and send notifications