Development Setup

Set up OsmoX for local development

Development Setup

This document outlines the steps required to set up OsmoX for development. By following these steps, you’ll be able to run the application locally.

Prerequisites

Before setting up OsmoX for development, ensure you have the following:

Node.js v20.x+

Install via NVM: nvm install 20 && nvm use 20

PostgreSQL v16.x+

Database server for storing notifications

Redis v6.x+

Queue backend for Bull

Git v2.x+

Version control system

Verify Services

Ensure Redis and PostgreSQL server are up and running:

sudo systemctl status redis
sudo systemctl status postgresql

Getting Started

1. Clone the repository

   git clone https://github.com/OsmosysSoftware/osmo-x.git
   cd osmo-x/apps/api
   
2. Install dependencies

   npm install
   
3. Configure environment

   Create a .env file from the example:

   cp .env.example .env
   

   Update the following values in your .env file:

   Variable	Description
   SERVER_PORT	API server port (default: 3000)
   DB_HOST	PostgreSQL host
   DB_PORT	PostgreSQL port
   DB_NAME	Database name
   DB_USERNAME	Database username
   DB_PASSWORD	Database password
   REDIS_HOST	Redis host

4. Run database migrations

   Ensure your database server is running, then create the tables:

   npm run typeorm:run-migration
   
5. Start the development server

   npm run start:dev
   

   OsmoX will now be running locally at http://localhost:3000.

Start the Scheduler

The scheduler is required for processing notifications. Without it, notifications will remain in Pending status.

Start the scheduler script in a separate terminal:

# Ensure API directory is active
cd osmo-x/apps/api

# Start scheduler script
./scheduler.sh

This script periodically calls OsmoX APIs to:

• Process all Pending notifications
• Confirm all Awaiting Confirmation notifications
• Archive completed notifications
• Delete old archived notifications (if enabled)

Docker Alternative

You can also run OsmoX using Docker while using a local database. See the Docker guide in apps/api/docs/use-local-db-instead-of-dockerized-db/README.md for details.

Next Steps

Usage Guide

Learn how to make API calls and send notifications

Configure Providers

Set up notification providers for your channels