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:

git clone <repository-url>
cd stupa-pdf-api

2. Run the development script:

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

docker compose -f docker-compose.watch.yml up --watch

2. View logs:

docker compose -f docker-compose.watch.yml logs -f api

3. Rebuild after major changes:

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:

docker compose version

Watch mode requires version 2.22.0 or higher.

2. Ensure proper file permissions:

chmod -R 755 src/

3. Try restarting the services:

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:

lsof -i :8000  # API port
lsof -i :3306  # MySQL port
lsof -i :8080  # Adminer port

2. View detailed logs:

docker compose -f docker-compose.watch.yml logs api

3. Rebuild from scratch:

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:

docker compose -f docker-compose.watch.yml ps

Ensure the db service shows as "healthy".

2. Test database connection:

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:

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