Installation Guide

Detailed installation instructions for different environments.

System Requirements

Python 3.11 or higher
Poetry package manager
Git

Development Installation

For developers wanting to contribute or modify Biomapper:

# Clone the repository
git clone https://github.com/arpanauts/biomapper.git
cd biomapper

# Install Poetry if not already installed
curl -sSL https://install.python-poetry.org | python3 -

# Install all dependencies including dev tools
poetry install --with dev,docs,api

# Activate the virtual environment
poetry shell

# Verify installation
poetry run pytest tests/unit/

Production Installation

For production use (API server only):

# Clone the repository
git clone https://github.com/arpanauts/biomapper.git
cd biomapper

# Install only runtime dependencies
poetry install --with api

# Start the API server directly from project root
poetry run uvicorn src.api.main:app --host 0.0.0.0 --port 8000

# API will be available at http://localhost:8000/api/docs

Docker Installation

Docker support is available for CI/testing purposes:

# Build the CI testing image
docker build -f Dockerfile.ci -t biomapper-ci:latest .

# Run tests in Docker environment
docker run biomapper-ci:latest poetry run pytest

Note: Production Docker deployment with docker-compose is under development.

CLI Installation

Install the Biomapper CLI tool:

# Install the CLI
poetry install

# Verify CLI installation
poetry run biomapper --help
poetry run biomapper health
poetry run biomapper test-import
poetry run biomapper strategies

Troubleshooting

Poetry not found: Install Poetry using the official installer: curl -sSL https://install.python-poetry.org | python3 -
Python version issues: Ensure Python 3.11+ is installed. Check with python3 --version
Permission errors: Run installation commands with appropriate permissions for your system.
ChromaDB installation issues: ChromaDB may require system dependencies. Install with: sudo apt-get install build-essential (Ubuntu/Debian) brew install gcc (macOS)
Import errors: Ensure you’re in the Poetry virtual environment: poetry shell

—

Verification Sources

Last verified: 2025-08-22

This documentation was verified against the following project resources:

/biomapper/pyproject.toml (Python 3.11+ requirement, Poetry dependency groups including dev/docs/api)
/biomapper/CLAUDE.md (Essential installation commands and environment setup procedures)
/biomapper/src/api/main.py (FastAPI application entry point with correct src-layout import paths)
/biomapper/src/cli/minimal.py (CLI commands including health, test-import, and strategies)
/biomapper/README.md (Installation instructions and dependency requirements verification)