Backend Installation & Setup

Prerequisites

• Python: 3.11 or higher
• PostgreSQL: 15 or higher
• Redis: 7.0 or higher (optional for caching)
• pip: Python package manager
• Docker: For containerized deployment (optional)

Development Setup

1. Clone the Repository

cd /path/to/certana
cd backend

2. Create Virtual Environment

# Using venv
python3.11 -m venv venv

# Activate
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

3. Install Dependencies

pip install -r requirements.txt

Key dependencies:

Package	Version	Purpose
fastapi	0.115.0	Web framework
uvicorn	0.32.0	ASGI server
sqlalchemy	2.0.35	ORM
pydantic	2.9.0	Data validation
asyncpg	0.30.0	Async PostgreSQL driver
torch	2.5.1	ML framework
transformers	4.46.0	Pretrained models
solana	0.35.0	Blockchain SDK

4. Environment Configuration

Create .env in the backend directory:

# Application
VERSION=1.0.0
ENVIRONMENT=development
SECRET_KEY=your-very-secret-key-change-in-production
MASTER_KEY=0123456789abcdef0123456789abcdef  # 32 hex chars (16 bytes)

# Database
DATABASE_URL=postgresql+asyncpg://certana:certana@localhost:5432/certana
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=10

# Redis (optional)
REDIS_URL=redis://localhost:6379/0

# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:8000

# JWT
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
JWT_REFRESH_TOKEN_EXPIRE_DAYS=30

# OAuth (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
OAUTH_REDIRECT_URI=http://localhost:8000/v1/auth/oauth/callback

# Storage
IPFS_API_URL=/ip4/127.0.0.1/tcp/5001
LIGHTHOUSE_API_KEY=your-lighthouse-api-key
FILECOIN_GATEWAY_URL=https://gateway.lighthouse.storage/ipfs
FILECOIN_STORAGE_ENABLED=true

# AWS S3 (optional)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1
S3_BUCKET_NAME=
CDN_BASE_URL=
S3_ENDPOINT_URL=

# Solana
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_PROGRAM_ID=CertXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
SOLANA_WALLET_PATH=./config/solana-wallet.json

# Watermarking
WATERMARK_TRACK_A_STRENGTH=0.3
WATERMARK_TRACK_B_STRENGTH=0.2
WATERMARK_TRACK_C_STRENGTH=0.4
WATERMARK_PAYLOAD_BITS=128

# Fingerprinting
CLIP_MODEL=openai/clip-vit-large-patch14
DINO_MODEL=facebook/dinov2-large
FINGERPRINT_INDEX_PATH=./data/fingerprint_index

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_PER_HOUR=1000
RATE_LIMIT_PER_DAY=10000

5. Set Up Database

Option A: Using Docker Compose

# Start PostgreSQL and Redis
docker-compose up -d

# Verify
docker ps

The docker-compose.yml includes PostgreSQL, Redis, and other services.

Option B: Local PostgreSQL

# Create database and user
createdb -U postgres certana
psql -U postgres -d certana -c "CREATE USER certana WITH PASSWORD 'certana';"
psql -U postgres -d certana -c "ALTER ROLE certana SUPERUSER;"

6. Run Database Migrations

# Using Alembic
alembic upgrade head

Check migrations:

alembic current  # Show current revision
alembic history  # Show all revisions

Create new migration:

alembic revision --autogenerate -m "Add new column"

7. Download ML Models

The first run will automatically download pretrained models:

# CLIP model (~1.7 GB)
# DINO model (~1.1 GB)
# These are cached locally after first download

For faster startup in development, you can pre-download:

python -c "
from transformers import CLIPVisionModel
from sentence_transformers import SentenceTransformer

print('Downloading CLIP...')
CLIPVisionModel.from_pretrained('openai/clip-vit-large-patch14')

print('Downloading DINO...')
from transformers import AutoModel
AutoModel.from_pretrained('facebook/dinov2-large')

print('Models downloaded!')
"

8. Create Solana Wallet

# Generate keypair for local testing
python -c "
from solders.keypair import Keypair
import json

keypair = Keypair()
wallet = {
    'address': str(keypair.pubkey()),
    'secret': keypair.secret().hex(),
}

with open('config/solana-wallet.json', 'w') as f:
    json.dump(wallet, f)

print(f'Wallet created: {wallet[\"address\"]}')
"

9. Run Development Server

# With auto-reload
python -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Output:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete

10. Verify Installation

# Health check
curl http://localhost:8000/health

# OpenAPI docs
open http://localhost:8000/docs

Docker Setup

Build Docker Image

cd backend
docker build -t certana-backend:latest .

Run with Docker Compose

# From project root
docker-compose up -d

# Check logs
docker-compose logs -f backend

# Stop
docker-compose down

Services started: - Backend: http://localhost:8000 - PostgreSQL: localhost:5432 - Redis: localhost:6379

Testing

Run Unit Tests

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test file
pytest tests/test_assets.py -v

Run Integration Tests

# Requires running backend and database
pytest tests/integration/ -v

Test API Endpoints

# Register user
curl -X POST http://localhost:8000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "Test123!",
    "full_name": "Test User"
  }'

# Login
curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "Test123!"
  }'

# Verify (no auth required)
curl -X POST http://localhost:8000/v1/verify/ \
  -F "file=@test_image.png"

Troubleshooting

Database Connection Error

sqlalchemy.exc.OperationalError: could not connect to server

Solution:

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Start PostgreSQL
brew services start postgresql  # macOS
sudo systemctl start postgresql  # Linux

Import Error: No module named 'torch'

# Reinstall with CPU version
pip uninstall torch torchvision
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

CUDA Out of Memory

# Set environment variable before running
export CUDA_VISIBLE_DEVICES=0  # Use first GPU only
# or use CPU
export CUDA_VISIBLE_DEVICES=

Solana Wallet Path Error

mkdir -p config
# Create wallet as shown above

Project Structure

backend/
├── src/
│   ├── api/                    # API endpoints
│   ├── models/                 # SQLAlchemy models
│   ├── schemas/                # Pydantic schemas
│   ├── services/               # Business logic
│   ├── core/                   # Configuration & utilities
│   ├── watermarking/           # Watermarking algorithms
│   ├── fingerprinting/         # Fingerprinting algorithms
│   └── main.py                 # Application entry
├── alembic/                    # Database migrations
├── config/                     # Configuration files
├── tests/                      # Test suite
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Container image
├── docker-compose.yml          # Multi-container setup
├── alembic.ini                 # Alembic config
└── .env                        # Environment variables (create this)

Next Steps

• Architecture Overview
• Database Schema
• Services Documentation
• API Reference
• Run Tests
• Deploy to Production

Quick Reference Commands

# Start development
python -m uvicorn src.main:app --reload

# Run migrations
alembic upgrade head
alembic downgrade -1

# Run tests
pytest -v

# Format code
black src/

# Lint code
flake8 src/

# Type check
mypy src/

# View API docs
open http://localhost:8000/docs

# Check database
psql -U certana -d certana