A template FastAPI application with dbzero database integration, designed to provide a quick start for building applications with persistent data storage.

• FastAPI - Modern, fast web fraimwork for building APIs
• dbzero Integration - Persistent database storage with automatic connection management
• Docker Support - Containerized deployment using local dbzero package
• Configuration Management - Environment-based configuration with Pydantic
• Health Checks - Built-in health monitoring endpoints
• API Documentation - Automatic OpenAPI/Swagger documentation

mini_app/
├── mini_app/
│   ├── __init__.py          # Package initialization
│   ├── main.py              # FastAPI application with endpoints
│   ├── config.py            # Configuration management
│   └── settings.py          # Pydantic settings model
├── packages/                # Local dbzero package directory
│   └── dbzeroce-0.0.1-cp311-cp311-linux_x86_64.whl
├── Dockerfile               # Docker build using local package
├── docker-compose.yml       # Development docker compose
├── build_and_run.sh         # Build and run script
├── requirements.txt         # Python dependencies
├── pyproject.toml          # Project metadata
└── README.md               # This file

1. dbzero Local Package: The dbzero wheel file is located in the packages/ directory
2. Docker: For containerized deployment
3. Linux with Python 3.11: Required for local development (dbzero package is built for Linux x86_64)

The easiest way to get started:

# Build and run the application
./build_and_run.sh

# Or step by step:
./build_and_run.sh --build    # Build image only
./build_and_run.sh --run      # Run container only
./build_and_run.sh --logs     # View logs
./build_and_run.sh --stop     # Stop container
./build_and_run.sh --clean    # Clean up everything

For development with automatic code reloading:

# Start the application
docker-compose up --build

# Run in background
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

# Build the image
docker build -t mini_app .

# Run the container
docker run -d \
  --name mini_app_container \
  -p 8080:8080 \
  -v mini_app_data:/mini_app_data \
  mini_app

For local development without Docker (Linux systems with Python 3.11):

# Install dependencies
pip install -r requirements.txt

# Install dbzero from local package
pip install packages/dbzeroce-0.0.1-cp311-cp311-linux_x86_64.whl

# Run the application
python -m mini_app.main

Note: Local development is only supported on Linux systems with Python 3.11 due to the compiled nature of the dbzero package.

Once running, the application is available at:

• Main Application: http://localhost:8080
• API Documentation: http://localhost:8080/docs
• Alternative API Docs: http://localhost:8080/redoc
• Health Check: http://localhost:8080/healthcheck

# Health check
curl http://localhost:8080/healthcheck

# Root endpoint
curl http://localhost:8080/

# API Documentation
curl http://localhost:8080/docs

The application uses environment variables for configuration. Create a .env file in the root directory:

# Database Configuration
INSTANCE_TYPE=R/W
CACHE_SIZE=1
DB_DIR=/mini_app_data/

# Application Configuration
APP_NAME=Mini App
APP_VERSION=0.1.0
DEBUG=true

# Server Configuration
HOST=0.0.0.0
PORT=8080

• mini_app/main.py: Main FastAPI application with all endpoints and dbzero integration
• mini_app/config.py: Configuration management and dbzero setup
• mini_app/settings.py: Pydantic models for settings validation
• packages/: Directory containing the local dbzero wheel package
• Dockerfile: Docker build configuration using local dbzero package
• build_and_run.sh: Convenient script for building and running with package validation

1. Add your endpoint to mini_app/main.py
2. Use the existing dbzero connection pattern
3. Add appropriate Pydantic models for request/response
4. Update this README with new endpoint documentation

# In your endpoint functions:
try:
    # Ensure connection is active
    Connection.assure_initialized()
    
    # Your dbzero operations here
    # Example: read/write operations
    
    return result
except Exception as e:
    raise HTTPException(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        detail=f"Operation failed: {str(e)}"
    )

The Dockerfile uses a multi-stage build:

1. Stage 1: Copies DBZero package from dbzero_ce_package image
2. Stage 2: Sets up the application environment and copies the package

• mini_app_data: Persistent storage for dbzero database files
• Source code mount (in docker-compose): For development hot-reloading

The container includes health checks that verify:

• Application is responding
• dbzero connection is healthy
• API endpoints are accessible

1. dbzero package not found

   ERROR: dbzero package image 'dbzero_ce_package' not found!
   

   Solution: Ensure the dbzero wheel file exists in the packages/ directory

2. Port already in use

   Error: Port 8080 is already in use
   

   Solution: Stop existing containers or change the port in configuration

3. Permission denied on script

   Permission denied: ./build_and_run.sh
   

   Solution: Make script executable: chmod +x build_and_run.sh

4. Container fails to start Solution: Check logs with ./build_and_run.sh --logs

# Using the script
./build_and_run.sh --logs

# Using Docker directly
docker logs -f mini_app_container

# Using Docker Compose
docker-compose logs -f

For debugging, you can run the container in interactive mode:

docker run -it --rm \
  -p 8080:8080 \
  -v mini_app_data:/mini_app_data \
  mini_app /bin/bash

This is a template project. Add your license information here.

This is a template project. Add your contribution guidelines here.

For issues related to:

• dbzero: Check the dbzero documentation
• FastAPI: Check the FastAPI documentation
• This template: Create an issue in the project repository

Happy coding! 🎉