# 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

```bash
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:

```bash
./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:

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

### 3. Build and Start Services

```bash
# 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:

```bash
# 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:

```bash
docker compose ps
```

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

Test the installation:

```bash
# 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
```bash
# Install Docker Compose V2
docker compose version
# If not found, update Docker Desktop or install manually
```

#### Port Already in Use
```bash
# 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
```bash
# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect
```

#### Database Connection Failed
```bash
# 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:

```bash
# 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
```bash
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
```bash
cd frontend
npm install
npm run dev
```

See [Development Guide](./DEVELOPMENT.md) for more details.

## Next Steps

- Review the [Configuration Guide](./CONFIGURATION.md) for advanced settings
- Check the [Quick Start Guide](./QUICK_START.md) to begin using the system
- Read the [API Reference](./API_REFERENCE.md) for integration options