Skip to content

Installation

Install Blacklake with minimal dependencies using modern Python tooling.

Requirements

  • Python: 3.12 or higher
  • Package Manager: uv (recommended) or pip
  • Platform: Linux, macOS, Windows

Quick Install

# Install with server extras
uv add blacklake[server]

# Or install specific extras
uv add blacklake[server,docs]

Using pip

# Install with server extras
pip install blacklake[server]

# Or install specific extras
pip install blacklake[server,docs]

Installation Options

Core Installation

# Minimal installation (CLI only)
uv add blacklake

Includes: - CLI commands (blacklake init, add, commit, etc.) - Object storage and repository management - Metadata system (JSON-LD, Dublin Core, FOAF, OWL) - S3-compatible storage

Server Installation

# Full server installation
uv add blacklake[server]

Additional includes: - FastAPI server - PostgreSQL database support - Alembic migrations - Solr search integration

Development Installation

# Development with all extras
uv add blacklake[server,dev,docs]

Additional includes: - Testing framework (pytest) - Code quality tools (ruff, mypy) - Documentation tools (mkdocs) - Pre-commit hooks

Platform-Specific Notes

Linux

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3.12 python3.12-venv

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Blacklake
uv add blacklake[server]

macOS

# Using Homebrew
brew install python@3.12
brew install uv

# Install Blacklake
uv add blacklake[server]

Windows

# Using winget
winget install Python.Python.3.12
winget install astral-sh.uv

# Install Blacklake
uv add blacklake[server]

Docker Installation

Using Docker Compose

# Clone repository
git clone https://github.com/sempervent/blacklake.git
cd blacklake

# Start all services
docker-compose up -d

# Install Blacklake in container
docker-compose exec api uv add blacklake[server]

Using Docker Image

# Pull official image
docker pull sempervent/blacklake:latest

# Run with S3 configuration
docker run -it \
  -e S3_ENDPOINT=http://localhost:9000 \
  -e S3_BUCKET=blacklake-data \
  -e S3_ACCESS_KEY=minioadmin \
  -e S3_SECRET_KEY=minioadmin \
  sempervent/blacklake:latest

Minimal Dependencies

Blacklake is designed with minimal dependencies:

Core Dependencies

click>=8.1.7          # CLI framework
boto3>=1.34.0         # S3/object storage
pydantic>=2.5.0       # Data validation
pyyaml>=6.0.1         # Configuration
rich>=13.7.0          # Terminal formatting
rdflib>=7.0.0         # RDF/JSON-LD processing
pyld>=2.0.0           # JSON-LD processing
pyshacl>=0.20.0       # SHACL validation

Server Dependencies

fastapi>=0.109.0      # Web framework
uvicorn[standard]>=0.27.0  # ASGI server
sqlalchemy>=2.0.25    # ORM
alembic>=1.13.1       # Database migrations
psycopg2-binary>=2.9.9  # PostgreSQL driver
pysolr>=3.9.0        # Solr client

Verification

Check Installation

# Verify installation
blacklake --version

# Expected output
blacklake, version 0.1.0

Test CLI Commands

# Test help
blacklake --help

# Test metadata commands
blacklake meta --help

Test Server

# Start server
blacklake server --help

# Expected output
Usage: blacklake server [OPTIONS]
  Start the Blacklake API server

Environment Setup

Required Environment Variables

# S3 Configuration
export S3_ENDPOINT="http://localhost:9000"
export S3_BUCKET="blacklake-data"
export S3_ACCESS_KEY="minioadmin"
export S3_SECRET_KEY="minioadmin"

# Database Configuration
export DATABASE_URL="postgresql://blacklake:blacklake@localhost:5432/blacklake"

# Solr Configuration
export SOLR_URL="http://localhost:8983/solr/blacklake"

Optional Environment Variables

# Server Configuration
export BLACKLAKE_HOST="0.0.0.0"
export BLACKLAKE_PORT="8000"
export BLACKLAKE_WORKERS="4"

# Logging Configuration
export BLACKLAKE_LOG_LEVEL="INFO"
export BLACKLAKE_LOG_FORMAT="json"

Troubleshooting

Python Version Issues

# Check Python version
python --version

# Should be 3.12 or higher
# If not, install correct version
uv python install 3.12

uv Installation Issues

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

Permission Issues

# Fix permission issues
sudo chown -R $USER:$USER ~/.local

# Or use virtual environment
uv venv
source .venv/bin/activate
uv add blacklake[server]

Network Issues

# Test S3 connectivity
curl -I http://localhost:9000/minio/health/live

# Test database connectivity
psql -h localhost -U blacklake -d blacklake -c "SELECT 1;"

# Test Solr connectivity
curl -I http://localhost:8983/solr/blacklake/admin/ping

Next Steps