Quickstart

Get OpenPay running on your machine in under 10 minutes. This guide walks you through cloning, configuring, and starting the entire platform.

Prerequisites

Docker & Docker Compose
Install from docker.com. We recommend Docker Desktop for Mac/Windows or Docker Engine for Linux.
Git
To clone the repository.
A Paystack account
Sign up at dashboard.paystack.co. You need a Secret Key and Public Key from the test environment.
4GB+ RAM available
The platform runs 10+ containers. Docker Desktop default of 2GB may not be enough.

Step 1: Clone the Repository

Open your terminal and clone the OpenPay repository:

terminal

git clone https://github.com/OpenPay-App/openpay.git
cd OpenPay

Step 2: Configure Environment Variables

Each service has its own environment file. Copy the example files and fill in your values:

copy .env files

# Copy the master environment file
cp .env.example .env

# Copy environment files for each service
cp event-bus/.env.example event-bus/.env
cp payment-system/hyperswitch/.env.example payment-system/hyperswitch/.env
cp payment-system/killbill/.env.example payment-system/killbill/.env
cp payment-system/nats-kb-bridge/.env.example payment-system/nats-kb-bridge/.env
cp monitoring-and-rules/.env.example monitoring-and-rules/.env

Now edit the main .env file and add your Paystack keys:

.env

# .env (main file)
POSTGRES_PASSWORD=your-secure-password-here
REDIS_PASSWORD=your-secure-password-here

# Paystack keys from dashboard.paystack.co
PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxx
PAYSTACK_PUBLIC_KEY=pk_test_xxxxxxxxxxxxxxxx
PAYSTACK_WEBHOOK_SECRET=your-webhook-secret

Important

Never commit your .env files to version control. They are already included in .gitignore.

Step 3: Start the Platform

Start all services with Docker Compose:

start services

# Using Make (recommended)
make up

# Or using Docker Compose directly
docker compose up -d

This starts all 10 services. It may take a few minutes on first run as Docker pulls the images. Watch the logs:

view logs

# Watch all logs
make logs

# Or watch a specific service
docker compose logs -f hyperswitch

Step 4: Initialize Event Streams

NATS JetStream needs its streams initialized. Run the setup script:

terminal

./event-bus/nats/scripts/init-streams.sh

Step 5: Set Up the Dashboard

The merchant dashboard is a Next.js app. Open a new terminal:

dashboard setup

cd apps/merchant-dashboard

# Install dependencies
npm install

# Copy Kinde environment file
cp .env.local.example .env.local

# Edit .env.local with your Kinde credentials
# (See the Authentication guide for details)

# Start the dev server
npm run dev

Step 6: Verify Everything Works

Service	URL	What to Expect
Merchant Dashboard	`http://localhost:3000`	Landing page with OpenPay branding
Hyperswitch API	`http://localhost:8081/health`	{"status":"ok"}
Kill Bill API	`http://localhost:8082/1.0/healthcheck`	Health check response
NATS Monitoring	`http://localhost:8222`	NATS monitoring dashboard
Traefik Dashboard	`http://localhost:8080`	Traefik router overview

What's Next?

Your OpenPay platform is running. Now let's process a payment.

Accept Your First Payment →