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

​
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

​
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