stupa-pdf-api/docs/INSTALLATION.md

Installation Guide

This guide will walk you through installing and setting up the STUPA PDF API system on your local machine or server.

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows (with WSL2)
• Memory: Minimum 4GB RAM (8GB recommended)
• Storage: At least 2GB free disk space
• Network: Internet connection for downloading dependencies

Required Software

• Docker: Version 20.10 or higher
• Docker Compose: Version 2.0 or higher
• Git: For cloning the repository
• Text Editor: For editing configuration files

Optional Software

• Make: For using the Makefile commands
• Node.js: Only if developing the frontend locally
• Python 3.11: Only if developing the backend locally

Installation Steps

1. Clone the Repository

git clone https://github.com/your-org/stupa-pdf-api.git
cd stupa-pdf-api

2. Create Environment Configuration

Use the provided script to create your .env file:

./scripts/create-env.sh

This script will:

• Ask for configuration values (with sensible defaults)
• Generate secure passwords automatically
• Create a .env file with all required variables

Alternatively, create .env manually:

cp .env.example .env
# Edit .env with your preferred editor

3. Build and Start Services

# Build all services
docker compose build

# Start all services in detached mode
docker compose up -d

This will start:

• MySQL database (port 3306)
• Backend API (port 8000)
• Frontend application (port 3000)
• Adminer database UI (port 8080)

4. Initialize Database

The database will be automatically initialized when the MySQL container starts. To run migrations manually:

# Execute migrations
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_comparison_offers_tables.sql
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_attachments_tables.sql
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_url_to_comparison_offers.sql
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${MYSQL_DB} < backend/src/migrations/add_is_preferred_to_comparison_offers.sql

5. Verify Installation

Check that all services are running:

docker compose ps

All services should show as "Up" and "Healthy".

Test the installation:

# Test API endpoint
curl http://localhost:8000/

# Test frontend
curl http://localhost:3000/

# You should see responses from both services

Post-Installation

Access Points

After successful installation, you can access:

• Frontend Application: http://localhost:3000
• API Documentation: http://localhost:8000/docs
• Alternative API Docs: http://localhost:8000/redoc
• Database UI (Adminer): http://localhost:8080
  • Server: db
  • Username: root or your configured MYSQL_USER
  • Password: Your configured password
  • Database: Your configured MYSQL_DB

Initial Setup

1. Test PDF Upload:

   • Navigate to http://localhost:3000
   • Upload a test PDF form
   • Verify it's processed correctly

2. Create Test Application:

   • Use the frontend to create a new application
   • Note the generated application ID and key

3. Verify Database:

   • Access Adminer at http://localhost:8080
   • Check that tables are created
   • Verify test data is stored

Troubleshooting Installation

Common Issues

Docker Compose Not Found

# Install Docker Compose V2
docker compose version
# If not found, update Docker Desktop or install manually

Port Already in Use

# Find process using port (example for port 3000)
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Change port in docker-compose.yml or stop conflicting service

Permission Denied

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Database Connection Failed

# Check MySQL container logs
docker compose logs db

# Verify environment variables
docker compose config

# Ensure database is healthy
docker compose ps db

Resetting Installation

To completely reset the installation:

# Stop all services
docker compose down

# Remove volumes (WARNING: Deletes all data)
docker compose down -v

# Remove all images
docker compose down --rmi all

# Start fresh
docker compose up -d

Development Installation

For local development without Docker:

Backend Development

cd backend
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

pip install -r requirements.txt
# Set environment variables
export MYSQL_HOST=localhost
# ... other variables
uvicorn src.service_api:app --reload

Frontend Development

cd frontend
npm install
npm run dev

See Development Guide for more details.

Next Steps

• Review the Configuration Guide for advanced settings
• Check the Quick Start Guide to begin using the system
• Read the API Reference for integration options