Skip to content

Installation

This guide covers how to install and run Ospobox in different environments.

Requirements

  • Python 3.12 or higher
  • uv (recommended) or pip for package management
  • SQLite (development) or PostgreSQL 14+ (production)
  • Redis (optional, for caching and rate limiting)

Development Setup

The easiest way to get started is using the provided Makefile:

# Clone the repository
git clone https://github.com/your-org/ospobox.git
cd ospobox

# Install all dependencies (uses uv)
make dev

# Copy and configure environment
cp .env.example .env

# Run database migrations — required, the app does not create tables
make migrate

# Start the development server
make run

The application will be available at http://localhost:8000.

Manual Installation

If you prefer manual installation:

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

# Install dependencies
pip install -e ".[dev]"

# Configure environment
cp .env.example .env

# Run migrations — the only thing that creates the schema
alembic upgrade head

# Start server
litestar run --reload

Production Deployment

Environment Variables

For production, you must configure these environment variables:

# Required
SECRET_KEY=<generate-a-secure-key>
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/ospobox
DEBUG=false

# Recommended
REDIS_URL=redis://localhost:6379/0
BASE_URL=https://your-domain.com

Secret Key

Generate a secure secret key for production: 

python -c "import secrets; print(secrets.token_urlsafe(32))"

Using Docker

The repository includes a production-ready multi-stage Dockerfile:

# Build the image
docker build -t ospobox .

# Run with environment file
docker run -p 8000:8000 --env-file .env.production ospobox

The image includes:

  • Multi-stage build for minimal size
  • Non-root user for security
  • Health check endpoint
  • Optimized for production

Using Docker Compose (Production)

For production with PostgreSQL and Redis:

# Copy and configure environment
cp .env.production.example .env

# Start all services
docker compose up -d

# View logs
docker compose logs -f

The docker-compose.yml includes:

  • PostgreSQL database
  • Redis for caching
  • Background worker
  • Health checks
  • Persistent volumes

Using Docker Compose (Development)

For local development with hot reload:

docker compose -f docker-compose.dev.yml up

This mounts the source directory for live code changes.

Database Migrations

Run migrations before starting the application:

# Apply all migrations
make migrate

# Or manually
alembic upgrade head

To create a new migration after model changes:

make migrate-new MSG="add new column"

Verifying Installation

After starting the application, verify it's working:

  1. Open http://localhost:8000/health - should return {"status": "healthy"}
  2. Open http://localhost:8000 - should show the home page
  3. Check the API docs at http://localhost:8000/docs

Troubleshooting

Common Issues

Port 8000 already in use

Another application is using port 8000. Either stop that application or run Ospobox on a different port: 

litestar run --port 8080

Database connection failed

Verify your DATABASE_URL is correct and the database server is running: 

# For PostgreSQL
psql -h localhost -U ospobox -d ospobox -c "SELECT 1"

SECRET_KEY error on startup

In production (DEBUG=false), you must set a secure SECRET_KEY. Generate one with: 

python -c "import secrets; print(secrets.token_urlsafe(32))"

Migration errors

If migrations fail, check that:

  1. The database exists and is accessible
  2. You have the latest code (git pull)
  3. Try resetting migrations (development only): 
    alembic downgrade base
alembic upgrade head

Next Steps