Skip to main content
This guide will walk you through the process of setting up the Definable backend development environment on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.10+ - The core programming language
  • Poetry - For dependency management
  • PostgreSQL 14+ - The main database
  • Redis - For caching and Celery task queue
  • Git - For version control
  • Docker (optional) - For containerized development
  • Node.js 20.17 (optional) - For sandbox servers
  • NVM (optional) - To manage Node.js versions

​
Clone the Repository

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

​
Setting Up Python Environment

We use Poetry for dependency management: 
# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install
Alternatively, you can use a virtual environment: 
# Create a virtual environment
python3.10 -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

​
Setting Up Pre-commit Hooks

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

​
Setting Up PostgreSQL

​
Option 1: Local PostgreSQL with Docker

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

​
Option 2: Using Supabase

If you don’t want to set up PostgreSQL locally, you can use Supabase as a managed 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
When using the connection string, replace [YOUR-PASSWORD] with your actual database password.

​
Connection String Types

Supabase offers different connection types for different use cases:
  1. Direct Connection:
    • Best for applications with persistent, long-lived connections
    • Format: postgresql://postgres:[YOUR-PASSWORD]@db.izufeytmzeanvqoyck...
    • Each client gets a dedicated connection to Postgres
  2. Transaction Pooler:
    • Ideal for stateless applications like serverless functions
    • Format: postgresql://postgres.izufeytmzeanvqoyckvp:[YOUR-PASSWORD]@...
    • Pre-warmed connection pool to Postgres
    • IPv4 compatible
  3. Session Pooler:
    • Alternative to Direct Connection when connecting via an IPv4 network
    • Format: postgresql://postgres.izufeytmzeanvqoyckvp:[YOUR-PASSWORD]@...
    • Only recommended if you have IPv4 compatibility issues

​
Configuration Files

The project requires configuration files. Template files are provided to help you get started: 
# Copy configuration templates
cp .env.local .env
cp alembic.copy.ini alembic.ini
Update the connection strings in both files to match your database setup.

​
Database Migrations

Set up the database schema using Alembic migrations: 
# Run migrations
alembic upgrade head

​
Setting Up Sandbox Servers (Optional)

If you want to develop or test tools that run dynamic code: 
# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

# Install Node.js
nvm install 20.17
nvm use 20.17

# Navigate to the Python tool tester
cd src/servers/python_tool_tester

# Install dependencies
npm install
npm install -g tsx

# Start the sandbox server
tsx index.ts

​
Running the Application

Start the application in development mode: 
# Run the FastAPI application with auto-reload
python -m src.app --dev
Or with FastAPI CLI (if installed): 
fastapi dev src/app.py
The API will be available at http://localhost:8000.

​
Docker Deployment

For a containerized environment, you can use Docker: 
# Build and start the services
docker-compose up -d

# View logs
docker-compose logs -f

​
Accessing the API Documentation

FastAPI automatically generates interactive API documentation:
  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc

​
Next Steps

After installation, you’ll need to set up your environment variables. See our Environment Setup guide to configure your application.

​
Troubleshooting

Ensure PostgreSQL is running and the database exists. Check your connection string in the .env file.
# Check if PostgreSQL is running
pg_isready

# Check if you can connect to your database
psql -U postgres -d postgres
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, try resetting the migration state:
# Downgrade to base
alembic downgrade base

# Then upgrade again
alembic upgrade head
If you’re using Supabase and experiencing connection issues, it may be related to IPv4/IPv6 compatibility:Symptoms:
  • Connection timeouts
  • “Could not connect to server” errors
  • Intermittent connection issues
Solution:
  1. Check if your network primarily uses IPv4 (many home and office networks do)
  2. If you’re on an IPv4 network, use the Session Pooler or Transaction Pooler connection string:
# Instead of Direct Connection
postgresql://postgres:[YOUR-PASSWORD]@db.izufeytmzeanvqoyck...

# Use Session Pooler
postgresql://postgres.izufeytmzeanvqoyckvp:[YOUR-PASSWORD]@...
  1. If you’re experiencing high latency, the Transaction Pooler is recommended as it maintains pre-warmed connections.
Supabase proxies Session and Transaction pooler connections for IPv4 networks, making them more reliable if you’re experiencing IPv6 compatibility issues.

​
Development Tools

We recommend these tools for an optimal development experience:
  • Cursor - AI-powered IDE recommended for development
  • VSCode with Python and FastAPI extensions
  • pgAdmin for PostgreSQL management
  • Redis Desktop Manager for Redis inspection
  • Insomnia or Postman for API testing
⌘I