Skip to main content

CODITECT Cloud Backend - Installation Guide

Python Version Compatibility​

Important: This project requires Python 3.11 or 3.12. Python 3.14 is too new and not yet fully supported by all dependencies.

Check Your Python Version​

python3 --version

If you have Python 3.14, you'll need to install Python 3.11 or 3.12:

macOS (Homebrew):

brew install python@3.11
# Use python3.11 instead of python3
python3.11 -m venv venv

Ubuntu/Debian:

sudo apt-get install python3.11 python3.11-venv
python3.11 -m venv venv

Installation Steps​

1. Create Virtual Environment​

# Using Python 3.11 (recommended)
python3.11 -m venv venv

# Or Python 3.12
python3.12 -m venv venv

2. Activate Virtual Environment​

source venv/bin/activate  # On Linux/macOS
# OR
venv\Scripts\activate  # On Windows

3. Upgrade pip​

pip install --upgrade pip setuptools wheel

4. Install Dependencies​

pip install -r requirements.txt

If you encounter build errors, install system dependencies:

macOS:

# Install Xcode Command Line Tools if not already installed
xcode-select --install

# Install PostgreSQL client libraries
brew install postgresql

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    libpq-dev \
    python3-dev

5. Configure Environment​

cp .env.example .env
# Edit .env with your database credentials

6. Verify Installation​

# Test imports
python3 -c "import fastapi, sqlalchemy, pydantic; print('All imports successful')"

# Test database connection (requires .env configured)
python3 -c "
import asyncio
from src.database import init_db
asyncio.run(init_db())
print('Database connection successful')
"

7. Run Development Server​

./run_dev.sh
# OR
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Troubleshooting​

Error: "Failed building wheel for asyncpg"​

This means you need PostgreSQL development headers:

# macOS
brew install postgresql

# Ubuntu/Debian
sudo apt-get install libpq-dev python3-dev

Error: "Failed building wheel for pydantic-core"​

This requires Rust compiler:

# macOS
brew install rust

# Ubuntu/Debian
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Error: Python version too new​

Downgrade to Python 3.11 or 3.12:

# macOS
brew install python@3.11
python3.11 -m venv venv

# Use pyenv for version management
brew install pyenv
pyenv install 3.11.7
pyenv local 3.11.7

If you encounter persistent installation issues, use Docker:

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements and install
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY src/ ./src/
COPY .env .env

# Run
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t coditect-backend .
docker run -p 8000:8000 coditect-backend

Next Steps​

Once installed successfully:

  1. Review readme-backend.md for API documentation
  2. Test endpoints with curl or Postman
  3. Run tests with pytest tests/
  4. Start development!