EPUB Upload & Validator Microservice

A lightweight HTTP microservice for uploading, validating, and storing EPUB files with optional Audiobookshelf integration.

Features

• HTTP endpoint for uploading EPUB files (POST /upload)
• Basic EPUB validation (ZIP structure + META-INF/container.xml)
• Secure file storage with atomic operations
• Optional Bearer token authentication
• Optional Audiobookshelf library rescan integration
• Health check endpoint (GET /health)
• Docker deployment with security hardening

Requirements

• Python 3.12+ or Docker

Configuration

The service is configured via environment variables:

Variable	Default	Purpose
UPLOAD_DIR	/ebooks	Target directory for validated EPUBs
MAX_FILE_SIZE	(unset)	Max file size (e.g., 50MB)
API_TOKEN	(unset)	Bearer token; if empty, no auth is enforced
ABS_URL	(unset)	Audiobookshelf base URL, e.g. http://abs.local:13378
ABS_TOKEN	(unset)	ABS API Bearer token
ABS_LIBRARY_ID	(unset)	Target Audiobookshelf library ID
ABS_FORCE_RESCAN	0	If 1, forces full rescan
PUID / PGID	1000	UID/GID of container user (matches host permissions)

Running with Docker

The easiest way to run the service is with Docker Compose:

1. Create a .env file with your configuration (optional):

API_TOKEN=your_secret_token
ABS_URL=http://your-audiobookshelf-server:13378
ABS_TOKEN=your_abs_token
ABS_LIBRARY_ID=your_library_id

2. Create the ebooks directory:

mkdir -p ebooks

3. Start the service:

docker-compose up -d

Running without Docker

1. Install the dependencies:

pip install -e .

2. Set environment variables:

export UPLOAD_DIR=./ebooks
export API_TOKEN=your_secret_token
# Set other variables as needed

3. Run the service:

python main.py

API Usage

Upload an EPUB file

# Without authentication
curl -F "file=@your-book.epub" http://localhost:8080/upload

# With authentication
curl -F "file=@your-book.epub" -H "Authorization: Bearer your_secret_token" http://localhost:8080/upload

Check service health

curl http://localhost:8080/health

Response Format

Successful upload:

{
  "status": "success",
  "filename": "your-book.epub",
  "bytes": 1234567,
  "path": "/ebooks/your-book.epub",
  "abs_rescan": {
    "success": true,
    "message": "Library scan triggered successfully"
  }
}

Security

The Docker deployment includes several security features:

• Non-root user execution
• Read-only root filesystem
• Minimal container with only required dependencies
• Dropped Linux capabilities
• No new privileges security option
• Bearer token authentication (when configured)

License

MIT