add aws deployment iac

Author: Henri93

.gitignore

@@ -24,3 +24,17 @@ test_data/
 # OS
 .DS_Store
 Thumbs.db
+
+# Deployment artifacts
+deployment/lambda_package.zip
+
+# Terraform
+terraform/.terraform/
+terraform/.terraform.lock.hcl
+terraform/terraform.tfstate
+terraform/terraform.tfstate.backup
+terraform/*.tfvars
+terraform/plan.out
+
+# AWS
+.aws/

README.md

@@ -5,7 +5,15 @@
 
 A simple Python/FastAPI server for syncing reading progress across KOReader devices.
 
-## Running Sync Server
+## Quick Start (Hosted Server)
+
+Don't want to deploy your own? Use the public sync server:
+
+**`https://null-space.xyz/reader`**
+
+Just point your KOReader or Readest app to this URL and create an account.
+
+## Running Sync Server (Self-Hosted)
 
 ### Local Development
 
@@ -22,12 +30,69 @@ uvicorn main:app --reload --port 8080
 docker compose up -d
 ```
 
+### AWS Lambda
+
+Deploy as a serverless Lambda function with DynamoDB storage.
+
+#### Prerequisites
+
+- AWS CLI configured with credentials
+- Terraform >= 1.0
+- Python 3.12
+
+#### One-Time Bootstrap
+
+Create the shared S3 bucket for Terraform state:
+
+```bash
+cd deployment
+./bootstrap.sh
+```
+
+#### Deploy
+
+1. Create terraform variables file:
+
+```bash
+cp deployment/terraform.tfvars.example terraform/terraform.tfvars
+```
+
+2. Edit `terraform/terraform.tfvars` with your password salt:
+
+```hcl
+password_salt = "your-secure-random-salt"  # Generate with: openssl rand -hex 32
+```
+
+3. Build and deploy:
+
+```bash
+./deployment/deploy.sh
+```
+
+This creates:
+- Lambda function (`reader-progress-prod`)
+- DynamoDB tables (`reader-progress-prod-users`, `reader-progress-prod-progress`)
+- IAM role with minimal permissions
+
 ## Configuration
 
+### Docker / Local Development
+
 | Environment Variable | Default | Description |
 |---------------------|---------|-------------|
-| PASSWORD_SALT | `default-salt-change-me` | Salt prepended to passwords before hashing |
-| DATABASE_URL | `sqlite:///./data/koreader.db` | SQLite database path |
+| `DB_BACKEND` | `sql` | Database backend (`sql` or `dynamodb`) |
+| `PASSWORD_SALT` | `default-salt-change-me` | Salt prepended to passwords before hashing |
+| `DATABASE_URL` | `sqlite:///./data/koreader.db` | SQLite/PostgreSQL database URL |
+
+### AWS Lambda
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `DB_BACKEND` | Set to `dynamodb` |
+| `PASSWORD_SALT` | Salt for password hashing (set via Terraform) |
+| `DYNAMODB_USERS_TABLE` | Users table name (set via Terraform) |
+| `DYNAMODB_PROGRESS_TABLE` | Progress table name (set via Terraform) |
+| `AWS_REGION` | AWS region (set via Terraform) |
 
 ## KOReader Setup
 
@@ -77,15 +142,17 @@ The document hash ensures the same book is identified across devices regardless
 
 ## Database Structure
 
-### Users Table
+### SQLite/PostgreSQL (Docker/Local)
+
+#### Users Table
 
 | Column | Type | Description |
 |--------|------|-------------|
 | id | INTEGER | Primary key |
 | username | TEXT | Unique username |
 | password_hash | TEXT | Bcrypt hash of salted MD5 password |
 
-### Progress Table
+#### Progress Table
 
 | Column | Type | Description |
 |--------|------|-------------|
@@ -100,6 +167,27 @@ The document hash ensures the same book is identified across devices regardless
 
 **Key constraint**: One progress record per (user_id, document) pair. Updates replace existing records.
 
+### DynamoDB (AWS Lambda)
+
+#### Users Table
+
+| Attribute | Type | Key |
+|-----------|------|-----|
+| username | String | Partition Key |
+| password_hash | String | - |
+
+#### Progress Table
+
+| Attribute | Type | Key |
+|-----------|------|-----|
+| user_id | String | Partition Key |
+| document | String | Sort Key |
+| progress | String | - |
+| percentage | Number | - |
+| device | String | - |
+| device_id | String | - |
+| timestamp | Number | - |
+
 ## API Reference
 
 ### Authentication

auth.py

@@ -3,9 +3,9 @@
 import hashlib
 import bcrypt
 from fastapi import Header, HTTPException, Depends
-from sqlalchemy.orm import Session
-from database import get_db
-from models import User
+
+from repositories import get_user_repository
+from repositories.protocols import UserEntity
 
 logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger(__name__)
@@ -33,15 +33,15 @@ def verify_password(password_md5: str, password_hash: str) -> bool:
 def get_current_user(
     x_auth_user: str = Header(None),
     x_auth_key: str = Header(None),
-    db: Session = Depends(get_db),
-) -> User:
+    user_repo=Depends(get_user_repository),
+) -> UserEntity:
     key_hint = f"'{x_auth_key[:8]}...' len={len(x_auth_key)}" if x_auth_key else "None"
     logger.debug(f"Auth: user='{x_auth_user}' key={key_hint}")
 
     if not x_auth_user or not x_auth_key:
         raise HTTPException(status_code=401, detail="Unauthorized")
 
-    user = db.query(User).filter(User.username == x_auth_user).first()
+    user = user_repo.get_by_username(x_auth_user)
     if not user:
         logger.debug(f"User '{x_auth_user}' not found")
         raise HTTPException(status_code=401, detail="Unauthorized")

deployment/bootstrap.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+set -e
+
+BUCKET_NAME="nullspace-terraform-state"
+REGION="us-east-1"
+
+echo "=== Terraform State Bucket Bootstrap ==="
+echo ""
+echo "This script creates the S3 bucket for Terraform remote state."
+echo "Run this once before deploying reader-progress or nullspace-website."
+echo ""
+
+# Check if bucket already exists
+if aws s3api head-bucket --bucket "$BUCKET_NAME" 2>/dev/null; then
+    echo "Bucket '$BUCKET_NAME' already exists."
+    exit 0
+fi
+
+echo "Creating S3 bucket: $BUCKET_NAME"
+aws s3api create-bucket \
+    --bucket "$BUCKET_NAME" \
+    --region "$REGION"
+
+echo "Enabling versioning..."
+aws s3api put-bucket-versioning \
+    --bucket "$BUCKET_NAME" \
+    --versioning-configuration Status=Enabled
+
+echo "Enabling encryption..."
+aws s3api put-bucket-encryption \
+    --bucket "$BUCKET_NAME" \
+    --server-side-encryption-configuration '{
+        "Rules": [
+            {
+                "ApplyServerSideEncryptionByDefault": {
+                    "SSEAlgorithm": "AES256"
+                }
+            }
+        ]
+    }'
+
+echo "Blocking public access..."
+aws s3api put-public-access-block \
+    --bucket "$BUCKET_NAME" \
+    --public-access-block-configuration '{
+        "BlockPublicAcls": true,
+        "IgnorePublicAcls": true,
+        "BlockPublicPolicy": true,
+        "RestrictPublicBuckets": true
+    }'
+
+echo ""
+echo "=== Bootstrap Complete ==="
+echo "S3 bucket '$BUCKET_NAME' is ready for Terraform state storage."

deployment/build_lambda.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+BUILD_DIR="$SCRIPT_DIR/build"
+OUTPUT_FILE="$SCRIPT_DIR/lambda_package.zip"
+
+echo "Building Lambda package..."
+
+# Clean previous build
+rm -rf "$BUILD_DIR"
+mkdir -p "$BUILD_DIR"
+
+# Check if Docker is available for cross-platform build
+if command -v docker &> /dev/null; then
+    echo "Using Docker for cross-platform build (Amazon Linux 2023)..."
+
+    # Install dependencies using Lambda Python image
+    docker run --rm \
+        --entrypoint "" \
+        -v "$PROJECT_ROOT:/var/task" \
+        -v "$BUILD_DIR:/var/build" \
+        public.ecr.aws/lambda/python:3.12 \
+        pip install -r /var/task/requirements-aws.txt -t /var/build --quiet --upgrade
+else
+    echo "Docker not found, using local pip (may not work on Lambda)..."
+    pip3 install -r "$PROJECT_ROOT/requirements-aws.txt" -t "$BUILD_DIR" --quiet --upgrade
+fi
+
+# Copy application code
+echo "Copying application code..."
+cp "$PROJECT_ROOT/main.py" "$BUILD_DIR/"
+cp "$PROJECT_ROOT/auth.py" "$BUILD_DIR/"
+cp "$PROJECT_ROOT/schemas.py" "$BUILD_DIR/"
+cp "$PROJECT_ROOT/lambda_handler.py" "$BUILD_DIR/"
+cp -r "$PROJECT_ROOT/repositories" "$BUILD_DIR/"
+
+# Create zip
+echo "Creating zip archive..."
+cd "$BUILD_DIR"
+rm -f "$OUTPUT_FILE"
+zip -r "$OUTPUT_FILE" . -x "*.pyc" -x "__pycache__/*" -x "*.dist-info/*" -x "*.egg-info/*"
+
+# Cleanup
+rm -rf "$BUILD_DIR"
+
+echo ""
+echo "Lambda package created: $OUTPUT_FILE"
+echo "Size: $(du -h "$OUTPUT_FILE" | cut -f1)"

deployment/deploy.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+TERRAFORM_DIR="$PROJECT_ROOT/terraform"
+
+echo "=== Reader Progress AWS Deployment ==="
+echo ""
+
+# Check prerequisites
+echo "Checking prerequisites..."
+
+if ! command -v terraform &> /dev/null; then
+    echo "Error: Terraform is not installed"
+    exit 1
+fi
+
+if ! command -v aws &> /dev/null; then
+    echo "Error: AWS CLI is not installed"
+    exit 1
+fi
+
+if ! aws sts get-caller-identity &> /dev/null; then
+    echo "Error: AWS credentials not configured"
+    exit 1
+fi
+
+echo "All prerequisites met."
+echo ""
+
+# Build Lambda package
+echo "Building Lambda package..."
+bash "$SCRIPT_DIR/build_lambda.sh"
+echo ""
+
+# Initialize Terraform
+echo "Initializing Terraform..."
+cd "$TERRAFORM_DIR"
+terraform init
+
+echo ""
+echo "Planning deployment..."
+terraform plan
+
+echo ""
+read -p "Do you want to apply these changes? (yes/no): " confirm
+if [ "$confirm" != "yes" ]; then
+    echo "Deployment cancelled."
+    exit 0
+fi
+
+echo ""
+echo "Applying changes..."
+terraform apply -auto-approve
+
+echo ""
+echo "=== Deployment Complete ==="
+echo ""
+echo "Lambda function deployed. Now update nullspace-website to add API Gateway routes."
+echo ""
+echo "Outputs:"
+terraform output

deployment/terraform.tfvars.example

@@ -0,0 +1,14 @@
+# Copy this file to terraform/terraform.tfvars and fill in the values
+
+# AWS region for deployment
+aws_region = "us-east-1"
+
+# Project name (used as prefix for all resources)
+project_name = "reader-progress"
+
+# Environment (dev, staging, prod)
+environment = "prod"
+
+# Password salt for bcrypt hashing (keep this secret!)
+# Generate with: openssl rand -hex 32
+password_salt = "your-secure-random-salt-here"

lambda_handler.py

@@ -0,0 +1,14 @@
+import os
+
+# Set DynamoDB backend before importing app
+os.environ.setdefault("DB_BACKEND", "dynamodb")
+
+from mangum import Mangum
+from main import app
+
+# Configure root_path for API Gateway path prefix (/reader)
+# This ensures FastAPI routes work correctly when accessed via /reader/...
+app.root_path = "/reader"
+
+# Mangum wraps the FastAPI ASGI app for Lambda
+handler = Mangum(app, lifespan="off")