Installation

BinoAuth provides multiple SDKs and deployment options to fit your needs. Choose the installation method that best matches your use case.

SDK Installation

React Applications

For React applications, install the React SDK:


npm install @binoauth/react
# or
yarn add @binoauth/react
# or
bun add @binoauth/react

Next.js Applications

For Next.js applications, install the Next.js-specific SDK:


npm install @binoauth/nextjs
# or
yarn add @binoauth/nextjs
# or
bun add @binoauth/nextjs

Node.js Applications

For backend Node.js applications or frameworks like Express:


npm install binoauth
# or
yarn add binoauth
# or
bun add binoauth

Core SDK (All Features)

For access to all BinoAuth features including admin operations:


npm install binoauth
# or
yarn add binoauth
# or
bun add binoauth

Self-Hosted Installation

Prerequisites

Before installing BinoAuth, ensure you have:

Node.js 18+ or Bun 1.0+
Python 3.11+
PostgreSQL 14+
Redis 6+
Docker (optional, recommended)

Using Docker Compose (Recommended)

The easiest way to get started with BinoAuth is using Docker Compose:

Clone the repository:


git clone https://github.com/binoauth/binoauth.git
cd binoauth

Copy the environment file:


cp .env.example .env

Update the .env file with your configuration:


# Database
DATABASE_URL=postgresql://binoauth:password@localhost:5432/binoauth
REDIS_URL=redis://localhost:6379/0
 
# Security
SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
 
# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@yourdomain.com
 
# OAuth Providers (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Start the services:


docker-compose up -d

Run database migrations:


docker-compose exec api python -m cli tenants migrations upgrade public

Create your first tenant:


docker-compose exec api python -m cli tenants create --name "My Company" --domain "mycompany.com"

Manual Installation

1. Database Setup

Create a PostgreSQL database:


CREATE DATABASE binoauth;
CREATE USER binoauth WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE binoauth TO binoauth;

2. API Server Setup


# Navigate to API directory
cd api/
 
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
 
# Install dependencies
pip install -r requirements.txt
 
# Set environment variables
export DATABASE_URL="postgresql://binoauth:password@localhost:5432/binoauth"
export REDIS_URL="redis://localhost:6379/0"
export SECRET_KEY="your-secret-key-here"
 
# Run migrations
python -m cli tenants migrations upgrade public
 
# Start the server
python run_service.py --reload

3. Frontend Setup

Install dependencies and start the development servers:


# Install all dependencies
bun install
 
# Start admin dashboard (port 3000)
bun run dev:admin
 
# Start auth frontend (port 3100)
bun run dev:frontend
 
# Start documentation (port 3200)
bun run dev:docs

Verification

After installation, verify that BinoAuth is running correctly:

1. API Health Check

Visit http://localhost:8000/health to check the API server status.

2. Admin Dashboard

Open http://localhost:3000 to access the admin dashboard.

3. Auth Frontend

Open http://localhost:3100 to see the authentication frontend.

4. Create Your First Application

Log into the admin dashboard
Create a new tenant
Create an OAuth application
Note the client ID and secret for integration

What’s Next?

Now that BinoAuth is installed, continue with:

Configuration - Set up your environment
Quick Start - Build your first integration
Core Concepts - Understand BinoAuth fundamentals

Common Issues

Port Conflicts

If you encounter port conflicts, you can change the default ports:


# API Server
python run_service.py --port 8080
 
# Frontend services
PORT=3001 bun run dev:admin
PORT=3101 bun run dev:frontend

Database Connection Issues

Ensure PostgreSQL is running and accessible:


# Test connection
psql -h localhost -p 5432 -U binoauth -d binoauth
 
# Check PostgreSQL status
sudo systemctl status postgresql

Redis Connection Issues

Verify Redis is running:


# Test Redis connection
redis-cli ping
 
# Check Redis status
sudo systemctl status redis

For more troubleshooting help, see our Troubleshooting Guide.