Getting Started

This guide covers setting up Bizon Platform for local development. For production deployment, see the Deployment section.

Prerequisites

Python 3.12 (bizon-core requires <3.13)
PostgreSQL 14+
Node.js 18+ (for UI development)
Docker & Docker Compose (optional, for containerized setup)

Quick Start with Docker

The fastest way to get started is using Docker Compose:

# Clone the repository
git clone https://github.com/bizon-data/bizon-platform.git
cd bizon-platform

# Start all services
docker compose up --build

This starts:

API at http://localhost:8000
UI at http://localhost:5173
PostgreSQL at localhost:5432
Worker for job execution

Local Development Setup

Install Backend Dependencies

# Using uv (recommended)
uv sync

# Install bizon-core locally (if developing both)
uv pip install -e /path/to/bizon-core[all]

Configure Environment

Create a .env file:

DATABASE_URL=postgresql+asyncpg://bizon:bizon@localhost:5432/bizon
JWT_SECRET_KEY=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")

Start PostgreSQL

# Using Docker
docker run -d --name bizon-postgres \
  -e POSTGRES_USER=bizon \
  -e POSTGRES_PASSWORD=bizon \
  -e POSTGRES_DB=bizon \
  -p 5432:5432 \
  postgres:14

Run Database Migrations
Terminal window
```
uv run alembic upgrade head
```
Start the API Server
Terminal window
```
uv run python -m bizon_platform
```
Start the Worker (in a separate terminal)
Terminal window
```
uv run python -m bizon_platform.worker
```
Start the UI (in a separate terminal)
Terminal window
```
cd ui
npm install
npm run dev
```

Seed Development Data

For testing, seed the database with sample users:

uv run python -m bizon_platform.scripts.seed_dev

This creates:

Organization: Acme Corp
Users (password: Password123!):
- owner@example.com - Owner role
- admin@example.com - Admin role
- member@example.com - Member role
- viewer@example.com - Viewer role
Domains: Marketing, Engineering

Configuration Reference

Required Environment Variables

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`JWT_SECRET_KEY`	Secret for JWT token signing
`ENCRYPTION_KEY`	Fernet key for config encryption

Optional Environment Variables

Variable	Default	Description
`HOST`	`0.0.0.0`	API server host
`PORT`	`8000`	API server port
`WORKER_POLL_INTERVAL`	`2`	Worker polling interval (seconds)
`CORS_ALLOWED_ORIGINS`	`["http://localhost:5173"]`	CORS origins

See Configuration for the complete list.

curl http://localhost:8000/api/health
# {"status":"healthy"}

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@example.com","password":"Password123!"}'