openpecha-backend

FastAPI-based backend for OpenPecha.

Project Structure

openpecha-backend/
├── main.py                 # FastAPI entry point
├── routers/                # API route handlers
├── database/               # Database layer
├── models.py               # Pydantic models
├── tests/                  # Test suite
├── requirements.txt        # Production dependencies
├── requirements_dev.txt    # Development dependencies
└── gunicorn.conf.py        # Production server config

Setup

1. Clone the repo

2. Create a virtual environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt
pip install -r requirements_dev.txt  # For development

4. Copy environment template and configure

cp .env.example .env
# Edit .env with your Neo4j and AWS credentials

Running the API

Development

From the repository root:

source .venv/bin/activate
uvicorn main:app --reload

Or without activating the virtual environment:

./.venv/bin/uvicorn main:app --reload

The API will be available at http://localhost:8000

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health check: http://localhost:8000/__/health

The app initializes Neo4j and S3 when NEO4J_URI is set in .env. To run only docs/health locally without database startup, temporarily unset NEO4J_URI:

unset NEO4J_URI
./.venv/bin/uvicorn main:app --reload

Production

gunicorn main:app -c gunicorn.conf.py

Running Tests

Tests spin up a disposable Neo4j container automatically via testcontainers. No manual Neo4j installation or env vars are needed.

Prerequisites

1. Install dev dependencies:

   pip install -r requirements_dev.txt

2. You need a running Docker-compatible runtime (Docker Desktop, Colima, Podman, etc.)

   • Docker Desktop works out of the box
   • Other runtimes — set DOCKER_HOST:

     export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock

Run tests

pytest tests/

Or with verbose output:

python -m pytest tests/ -v

The first run will pull the neo4j:2026.07.1 image (~500 MB), which is cached for subsequent runs.

Deployment

Deployment is handled automatically via GitHub Actions when pushing to main.

Manual Deployment (EC2)

ssh ubuntu@<EC2_HOST>
cd /opt/openpecha-backend
git pull origin main
source .venv/bin/activate
pip install -r requirements.txt
sudo systemctl restart openpecha-api

Environment Configuration

• Neo4j: Configured via NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD in .env
• AWS S3: Configured via AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET in .env
• OpenSearch content search: Configured via OPENSEARCH_ENDPOINT
• OpenSearch catalog search (person/text name and title search): Configured via OPENSEARCH_ENDPOINT and OPENSEARCH_CATALOG_INDEX. Requires the analysis-tibetan and analysis-bdrc OpenSearch plugins on the cluster; for local tests set OPENSEARCH_TIBETAN_PLUGIN_ZIP and OPENSEARCH_BDRC_PLUGIN_ZIP. See docs/api-documentation/catalog-search-api.md.

Documentation

API documentation available at: https://pecha-backend.web.app/docs