stupa-pdf-api/docs/DEVELOPMENT.md

# Development Setup

This guide explains how to run the STUPA PDF API in development mode with automatic file watching and hot reloading.

## Prerequisites

- Docker Engine 20.10 or higher
- Docker Compose 2.22.0 or higher (for watch mode support)
- Git

## Quick Start

1. Clone the repository:
```bash
git clone <repository-url>
cd stupa-pdf-api
```

2. Run the development script:
```bash
./dev.sh
```

This will:
- Create a `.env` file with default values (if it doesn't exist)
- Build the development Docker image
- Start all services with file watching enabled
- Automatically reload the API when Python files change

## Development Mode Features

### File Watching

The development setup uses Docker Compose's watch feature to automatically handle file changes:

- **Python source files (`./src`)**: Changes trigger automatic reload via uvicorn
- **PDF templates (`./assets`)**: Changes are synced immediately
- **Requirements (`requirements.txt`)**: Changes trigger container rebuild

### Hot Reloading

The API service runs with uvicorn's `--reload` flag, which means:
- Python code changes are detected automatically
- The server restarts without rebuilding the container
- Your changes are reflected immediately

### Services

When running in development mode, the following services are available:

- **API**: http://localhost:8000
- **API Documentation**: http://localhost:8000/docs
- **Adminer (Database UI)**: http://localhost:8080

### Database Access

Default database credentials (defined in `.env`):
- Database: `stupa`
- Username: `stupa`
- Password: `secret`
- Root Password: `rootsecret`

You can access the database through:
1. Adminer at http://localhost:8080
2. MySQL client: `mysql -h localhost -P 3306 -u stupa -psecret stupa`

## Manual Development Setup

If you prefer to run commands manually:

1. Start services with watch mode:
```bash
docker compose -f docker-compose.watch.yml up --watch
```

2. View logs:
```bash
docker compose -f docker-compose.watch.yml logs -f api
```

3. Rebuild after major changes:
```bash
docker compose -f docker-compose.watch.yml build
docker compose -f docker-compose.watch.yml up --watch
```

## Development Workflow

1. **Making API Changes**:
   - Edit files in `./src`
   - Changes are automatically detected and the server reloads
   - Check the console for any errors

2. **Adding Dependencies**:
   - Add the package to `requirements.txt`
   - The container will automatically rebuild
   - Wait for the rebuild to complete before testing

3. **Updating PDF Templates**:
   - Replace files in `./assets`
   - Changes are synced immediately
   - No restart required

4. **Database Changes**:
   - Use Adminer at http://localhost:8080
   - Or connect with your preferred MySQL client

## Troubleshooting

### Watch mode not working

If file changes aren't being detected:

1. Check Docker Compose version:
```bash
docker compose version
```
Watch mode requires version 2.22.0 or higher.

2. Ensure proper file permissions:
```bash
chmod -R 755 src/
```

3. Try restarting the services:
```bash
docker compose -f docker-compose.watch.yml down
docker compose -f docker-compose.watch.yml up --watch
```

### Container fails to start

1. Check if ports are already in use:
```bash
lsof -i :8000  # API port
lsof -i :3306  # MySQL port
lsof -i :8080  # Adminer port
```

2. View detailed logs:
```bash
docker compose -f docker-compose.watch.yml logs api
```

3. Rebuild from scratch:
```bash
docker compose -f docker-compose.watch.yml down -v
docker compose -f docker-compose.watch.yml build --no-cache
docker compose -f docker-compose.watch.yml up --watch
```

### Database connection issues

1. Wait for MySQL to be fully ready:
```bash
docker compose -f docker-compose.watch.yml ps
```
Ensure the `db` service shows as "healthy".

2. Test database connection:
```bash
docker compose -f docker-compose.watch.yml exec db mysql -u stupa -psecret -e "SELECT 1"
```

## Environment Variables

The following environment variables can be configured in `.env`:

| Variable | Default | Description |
|----------|---------|-------------|
| `MYSQL_DB` | `stupa` | Database name |
| `MYSQL_USER` | `stupa` | Database user |
| `MYSQL_PASSWORD` | `secret` | Database password |
| `MYSQL_ROOT_PASSWORD` | `rootsecret` | MySQL root password |
| `MASTER_KEY` | `change_me_in_production` | Admin API key |
| `RATE_IP_PER_MIN` | `60` | Rate limit per IP |
| `RATE_KEY_PER_MIN` | `30` | Rate limit per API key |
| `TZ` | `Europe/Berlin` | Timezone |

## Tips

1. **Use the API documentation**: Visit http://localhost:8000/docs for interactive API testing
2. **Monitor logs**: Keep a terminal open with `docker compose -f docker-compose.watch.yml logs -f api`
3. **Database GUI**: Use Adminer for easy database inspection and modification
4. **Clean rebuild**: If you encounter issues, try `docker compose -f docker-compose.watch.yml down -v` to remove volumes

## Production

For production deployment, use the standard `docker-compose.yml` file without watch mode:

```bash
docker compose up -d
```

Never use the development setup in production as it includes:
- Debug mode enabled
- Hot reloading (performance overhead)
- Development dependencies
- Relaxed security settings