Getting Started

Sharpnr Suite is a collection of business applications designed to work together seamlessly. This guide will walk you through everything you need to get the suite running locally.

Prerequisites

Before you begin, make sure you have the following installed on your system:

Node.js v22+

Required for running all JavaScript-based services

Docker

Used for containerizing services and databases

PostgreSQL

Primary database for all Sharpnr apps

You will also need the following tools:

Git — for cloning the repository
Make — for running the provided Makefile commands
Nginx — for serving apps via reverse proxy

Installation

Clone the repo

git clone https://github.com/sharpnr/sharpnr_suite.git
cd sharpnr_suite

Install all dependencies

This installs dependencies for all apps in the suite at once:

npm install

Copy the environment file

Each app has its own .env.example. Start with the root one:

cp .env.example .env

Then open .env and fill in your database credentials, secret keys, and app URLs.

Set up the database

Run migrations to set up the PostgreSQL schema:

make db:migrate

Start the suite

make dev

This starts all apps concurrently in development mode.

Environment Variables

Each app in the suite requires its own environment variables. Here's an overview of the most important ones:

Project Structure

After cloning, your project will look like this:

sharpnr_suite/
├── sharp-auth/          # Authentication & Authorization
├── sharp-accounting/    # Finance & Accounting
├── sharp-iam/           # Identity & Access Management
├── sharp-ui/            # Shared UI Component Library
├── sharp-hr/            # Human Resources
├── sharp-marketing/     # Marketing tools
├── sharp-cortex/        # AI & Intelligence layer
├── orchestrator/        # Central management app
├── docs/                # This documentation site
├── makefile             # Common dev commands
└── ports.md             # Port assignments for each app

Each app is independently deployable but shares authentication through Sharp Auth.

Running Individual Apps

You don't have to run the entire suite at once. To start a specific app:

# Start only Sharp Auth
make dev:auth

# Start only Sharp Accounting
make dev:accounting

# Start only Orchestrator
make dev:orchestrator

Nginx Setup

All apps are served through Nginx using .sharpnr.test subdomains in development. Add the following to your /etc/hosts:

127.0.0.1 sharpnr.test
127.0.0.1 auth.sharpnr.test
127.0.0.1 accounting.sharpnr.test
127.0.0.1 iam.sharpnr.test
127.0.0.1 orchestrator.sharpnr.test
127.0.0.1 docs.sharpnr.test

Then reload Nginx:

sudo nginx -s reload

Verifying the Setup

Check Sharp Auth

Open http://auth.sharpnr.test — you should see the login page.

Check Orchestrator

Open http://orchestrator.sharpnr.test — the app management dashboard should load.

Check the Docs

Open http://docs.sharpnr.test — you're already here!

Common Issues

If you see a 502 Bad Gateway error in Nginx, the app on that port hasn't started yet. Check make dev output for errors.

If database migrations fail, make sure PostgreSQL is running and your DATABASE_URL is correct in .env.

Never commit your .env file. It contains secrets and is already listed in .gitignore.