Skip to main content
This guide will help you set up and run Definable on your local machine for development and testing purposes.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Python 3.10 or later (recommended)
  • PostgreSQL 14+ (required for vector storage)
  • Poetry (for dependency management)
  • Docker (optional, for containerized setup)
  • Git (for version control)

​
Clone the Repository

First, clone the repository from GitHub: 
git clone https://github.com/definable-io/definable.backend.git
cd definable.backend

​
Python Environment Setup

We recommend using Poetry for dependency management: 
# Install Poetry if you don't have it already
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install
Make sure you’re using Python 3.10 or later. You can check your version with python --version.

​
Pre-commit Setup

We use pre-commit hooks to ensure code quality: 
pre-commit install
This will configure automatic linting and type checking before each commit.

​
Environment Configuration

  1. Create your environment file by copying the example file:
cp .env.local .env
  1. Configure the following essential environment variables in your .env file:
# Application
APP_NAME=definable-backend
ENVIRONMENT=dev

# Security
JWT_SECRET=your_secret_key_here
MASTER_API_KEY=your_master_api_key_here
JWT_EXPIRE_MINUTES=1400

# Database
DATABASE_URL=postgresql+asyncpg://postgres:mysecretpassword@localhost:5432/postgres

# External APIs
OPENAI_API_KEY=your_openai_key_here
FRONTEND_URL=http://localhost:8000
Generate secure random strings for JWT_SECRET and MASTER_API_KEY. You can use Python’s secrets module: python -c "import secrets; print(secrets.token_hex(32))".

​
Database Setup

The easiest way to set up PostgreSQL is using Docker: 
docker run --name definable-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres

​
Option 2: Using Supabase

If you prefer a cloud-based PostgreSQL service:
  1. Create a Supabase account at supabase.com
  2. Create a new project
  3. Navigate to the Database settings in your Supabase dashboard
  4. Copy the connection string from the “Connection Pooling” section
Supabase offers different connection string formats for different network setups:
  1. Direct Connection:
    • Format: postgresql://postgres:[YOUR-PASSWORD]@db.xxxxxxxxxxx.supabase.co:5432/postgres
    • Best for persistent connections
  2. Session Pooler:
    • Format: postgresql://postgres.xxxxxxxxxxx:[YOUR-PASSWORD]@...
    • Recommended if you’re on an IPv4 network and have connection issues
  3. Transaction Pooler:
    • Similar to Session Pooler but optimized for short-lived connections
    • Good for stateless applications
If you experience connection issues, try the Session Pooler connection string.

​
Database Migrations Setup

  1. Copy the Alembic configuration template:
cp alembic.copy.ini alembic.ini
  1. Edit alembic.ini and update the sqlalchemy.url to match your database URL:
# For local Docker PostgreSQL
sqlalchemy.url = postgresql+asyncpg://postgres:mysecretpassword@localhost:5432/postgres
If your database password contains special characters like @, remember to URL-encode them in your .env file, but in the alembic.ini file, you need to escape % by doubling it: %%.
  1. Apply database migrations:
alembic upgrade head

​
Running the Application

Start the application in development mode: 
# Using Python directly
python -m src.app --dev

# OR using FastAPI CLI (if installed)
fastapi dev src/app.py
The API will be available at:
  • API Endpoints: http://localhost:8000/api/
  • Swagger UI Documentation: http://localhost:8000/docs
  • ReDoc Documentation: http://localhost:8000/redoc

​
Docker Deployment (Alternative)

For a fully containerized setup: 
# Build and start services
docker-compose up -d

# View logs
docker-compose logs -f

​
Verification

To verify your setup is working:
  1. Open http://localhost:8000/docs in your browser
  2. Try creating a new user account via the /api/auth/signup endpoint
  3. Login with the created account via /api/auth/login

​
Troubleshooting

If you’re having trouble connecting to your database:
  • Check if PostgreSQL is running: pg_isready
  • Verify your connection string format
  • Ensure your firewall allows connections to port 5432
  • Try connecting with psql to verify credentials
If you encounter issues with Poetry:
# Update Poetry
poetry self update

# Clear Poetry cache
poetry cache clear pypi --all

# Update dependencies
poetry update
If migrations fail:
# Check Alembic history
alembic history

# Reset migrations if needed
alembic downgrade base
alembic upgrade head
If using Supabase and experiencing connection problems:
  • Try the Session Pooler connection string instead of Direct Connection
  • Check if your network primarily uses IPv4 (common in many environments)
  • Supabase proxies Session and Transaction pooler connections for IPv4 networks

​
What’s Next?

Now that you have Definable running, explore:

Development Workflow

Learn our coding standards and contribution process

Architecture Overview

Understand how Definable is structured

Authentication

Learn about securing your API endpoints

Knowledge Base

Explore our vector database integration
⌘I