Skip to content

Quickstart Guide

Get up and running with the Rego backend API in minutes.

Prerequisites

  • Python 3.11+
  • PostgreSQL 14+
  • Redis 6+
  • Docker & Docker Compose (optional, recommended)

Quick Setup with Docker

The fastest way to get started is using Docker Compose:

1. Clone the Repository

git clone https://github.com/RegoFlow/Rego.git
cd Rego

2. Create Environment File

Create a .env file in the project root:

# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=rego

# Redis
REDIS_URL=redis://redis:6379

# JWT Secret (CHANGE THIS in production!)
JWT_SECRET=your-secret-key-change-me-in-production

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:3000

# Environment
ENVIRONMENT=development

3. Start Services

docker compose up -d

This starts: - PostgreSQL database on port 5432 - Redis on port 6379 - Backend API on port 8000 - Frontend on port 3000 (if included)

4. Run Database Migrations

docker compose exec backend alembic upgrade head

5. Verify Installation

Check the health endpoint:

curl http://localhost:8000/health

You should see:

{
  "status": "healthy",
  "postgres": "connected",
  "redis": "connected"
}

Manual Setup (Without Docker)

1. Install Dependencies

From backend/rego/:

# Using uv (recommended)
uv sync

# Or using pip
pip install -r requirements.txt

2. Setup PostgreSQL

Create a database:

CREATE DATABASE rego;
CREATE USER rego_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE rego TO rego_user;

3. Setup Redis

Start Redis:

redis-server

Or install and run as a service.

4. Configure Environment

Create backend/rego/.env:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=rego_user
POSTGRES_PASSWORD=your_password
POSTGRES_DB=rego

REDIS_URL=redis://localhost:6379

JWT_SECRET=your-secret-key-at-least-32-chars-long
CORS_ALLOWED_ORIGINS=http://localhost:3000

ENVIRONMENT=development

5. Run Migrations

cd backend/rego
alembic upgrade head

6. Start the Server

# Using uv
uv run uvicorn rego.main:app --reload --host 0.0.0.0 --port 8000

# Or if in venv
uvicorn rego.main:app --reload --host 0.0.0.0 --port 8000

Making Your First API Calls

1. Register a User

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "username": "testuser",
    "password": "SecurePass123!",
    "firstname": "Test",
    "lastname": "User"
  }'

2. Login

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=test@example.com&password=SecurePass123!"

Save the returned token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

3. Create a Board

TOKEN="your_token_here"

curl -X POST http://localhost:8000/boards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Board",
    "description": "Getting started with Rego"
  }'

4. Create a Column

BOARD_ID="board_id_from_previous_response"

curl -X POST http://localhost:8000/boards/$BOARD_ID/columns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "To Do",
    "color": "#3498db"
  }'

5. Create a Card

COLUMN_ID="column_id_from_previous_response"

curl -X POST http://localhost:8000/boards/$BOARD_ID/columns/$COLUMN_ID/cards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first task",
    "description": "This is a test card"
  }'

6. Get Board with All Data

curl http://localhost:8000/boards/$BOARD_ID \
  -H "Authorization: Bearer $TOKEN"

Using the API with Python

Here's a simple Python client:

import requests

class RegoClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
        self.token = None

    def register(self, email, username, password):
        response = requests.post(
            f"{self.base_url}/auth/register",
            json={
                "email": email,
                "username": username,
                "password": password
            }
        )
        response.raise_for_status()
        return response.json()

    def login(self, email, password):
        response = requests.post(
            f"{self.base_url}/auth/login",
            data={
                "username": email,
                "password": password
            }
        )
        response.raise_for_status()
        self.token = response.json()["access_token"]
        return self.token

    def _headers(self):
        return {"Authorization": f"Bearer {self.token}"}

    def create_board(self, title, description=None):
        response = requests.post(
            f"{self.base_url}/boards",
            headers=self._headers(),
            json={"title": title, "description": description}
        )
        response.raise_for_status()
        return response.json()

    def create_column(self, board_id, title):
        response = requests.post(
            f"{self.base_url}/boards/{board_id}/columns",
            headers=self._headers(),
            json={"title": title}
        )
        response.raise_for_status()
        return response.json()

    def create_card(self, board_id, column_id, title, description=None):
        response = requests.post(
            f"{self.base_url}/boards/{board_id}/columns/{column_id}/cards",
            headers=self._headers(),
            json={"title": title, "description": description}
        )
        response.raise_for_status()
        return response.json()

# Usage
client = RegoClient()
client.login("test@example.com", "SecurePass123!")

board = client.create_board("My Project")
column = client.create_column(board["id"], "To Do")
card = client.create_card(board["id"], column["id"], "First task")

print(f"Created card: {card['id']}")

Using the API with JavaScript

For frontend applications:

class RegoClient {
  constructor(baseUrl = 'http://localhost:8000') {
    this.baseUrl = baseUrl;
    this.token = null;
  }

  async register(email, username, password) {
    const response = await fetch(`${this.baseUrl}/auth/register`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, username, password })
    });
    return response.json();
  }

  async login(email, password) {
    const formData = new URLSearchParams();
    formData.append('username', email);
    formData.append('password', password);

    const response = await fetch(`${this.baseUrl}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: formData
    });

    const data = await response.json();
    this.token = data.access_token;
    return this.token;
  }

  async createBoard(title, description = null) {
    const response = await fetch(`${this.baseUrl}/boards`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ title, description })
    });
    return response.json();
  }

  async createColumn(boardId, title) {
    const response = await fetch(
      `${this.baseUrl}/boards/${boardId}/columns`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ title })
      }
    );
    return response.json();
  }

  async createCard(boardId, columnId, title, description = null) {
    const response = await fetch(
      `${this.baseUrl}/boards/${boardId}/columns/${columnId}/cards`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ title, description })
      }
    );
    return response.json();
  }
}

// Usage
const client = new RegoClient();
await client.login('test@example.com', 'SecurePass123!');

const board = await client.createBoard('My Project');
const column = await client.createColumn(board.id, 'To Do');
const card = await client.createCard(board.id, column.id, 'First task');

console.log('Created card:', card.id);

WebSocket Connection

Connect to real-time updates:

const token = 'your_jwt_token';
const boardId = 'your_board_id';

const ws = new WebSocket(
  `ws://localhost:8000/ws/boards/${boardId}?token=${token}`
);

ws.onopen = () => {
  console.log('Connected to board');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.type === 'ping') {
    // Respond to heartbeat
    ws.send(JSON.stringify({ type: 'pong' }));
  } else if (message.type === 'card.created') {
    console.log('New card created:', message.data);
  } else if (message.type === 'card.updated') {
    console.log('Card updated:', message.data);
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected from board');
};

Interactive API Documentation

The backend provides interactive API documentation:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

These interfaces let you explore and test endpoints directly in your browser.

Common Tasks

Get All Boards

curl http://localhost:8000/boards \
  -H "Authorization: Bearer $TOKEN"

Move a Card

curl -X POST http://localhost:8000/cards/$CARD_ID/move \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": "target_column_id",
    "position": 0
  }'

Assign Users to Card

curl -X PUT http://localhost:8000/cards/$CARD_ID/assignees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_id_1", "user_id_2"]
  }'

Create a Label

curl -X POST http://localhost:8000/boards/$BOARD_ID/labels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bug",
    "color": "#e74c3c"
  }'

Add Label to Card

curl -X POST http://localhost:8000/cards/$CARD_ID/labels/$LABEL_ID \
  -H "Authorization: Bearer $TOKEN"

Development Tools

Running Tests

cd backend/rego
pytest

Running with Hot Reload

uvicorn rego.main:app --reload

Viewing Logs

# Docker
docker compose logs -f backend

# Local
# Logs are output to stdout

Database Migrations

# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

Next Steps

Now that you're set up, explore the detailed documentation:

Troubleshooting

Database Connection Errors

Check that PostgreSQL is running and credentials are correct:

psql -h localhost -U rego_user -d rego

Redis Connection Errors

Verify Redis is running:

redis-cli ping
# Should return: PONG

JWT Token Errors

Ensure your JWT_SECRET is set and at least 32 characters in production.

CORS Errors

Add your frontend URL to CORS_ALLOWED_ORIGINS in .env.

Port Already in Use

Change the port in the uvicorn command:

uvicorn rego.main:app --port 8001

Getting Help

  • Documentation: Full docs in docs/api/
  • Issues: https://github.com/RegoFlow/Rego/issues
  • Discussions: https://github.com/RegoFlow/Rego/discussions

Happy coding!