Local Dev Setup

This page helps you run ActingWeb locally with your choice of database backend (DynamoDB or PostgreSQL) and web framework.

Install

# Minimal (no database backend)
pip install actingweb

# Flask integration + DynamoDB
pip install 'actingweb[flask,dynamodb]'

# Flask integration + PostgreSQL
pip install 'actingweb[flask,postgresql]'

# FastAPI integration + DynamoDB
pip install 'actingweb[fastapi,dynamodb]'

# FastAPI integration + PostgreSQL
pip install 'actingweb[fastapi,postgresql]'

# MCP-enabled (FastAPI + MCP + database)
pip install 'actingweb[fastapi,mcp,postgresql]'  # or dynamodb

# All extras (both backends, all integrations)
pip install 'actingweb[all]'

Database Backend Setup

ActingWeb supports two database backends: DynamoDB and PostgreSQL. Choose one for local development.

Option 1: DynamoDB Local

Launch DynamoDB Local and configure environment:

docker run -p 8000:8000 amazon/dynamodb-local

export DATABASE_BACKEND=dynamodb  # Optional, dynamodb is default
export AWS_ACCESS_KEY_ID=local
export AWS_SECRET_ACCESS_KEY=local
export AWS_DEFAULT_REGION=us-east-1
export AWS_DB_HOST=http://localhost:8000   # IMPORTANT for PynamoDB models

Notes:

• The library auto-creates tables on first access through its PynamoDB models.

• For production, configure IAM and real AWS hosts (do not set AWS_DB_HOST).

Option 2: PostgreSQL (Recommended for New Projects)

Quick Start (Complete Setup)

# 1. Start PostgreSQL (Docker)
docker run -d \
  --name actingweb-postgres \
  -e POSTGRES_USER=actingweb \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=actingweb \
  -p 5432:5432 \
  postgres:16-alpine

# 2. Create .env file in your project root
cat > .env << 'EOF'
DATABASE_BACKEND=postgresql
PG_DB_HOST=localhost
PG_DB_PORT=5432
PG_DB_NAME=actingweb
PG_DB_USER=actingweb
PG_DB_PASSWORD=devpassword
EOF

# 3. Download migration helper script (one-time setup)
mkdir -p scripts
curl -o scripts/migrate_db.py https://raw.githubusercontent.com/actingweb/actingweb/main/scripts/migrate_db.py

# 4. Run migrations (REQUIRED before first use)
python scripts/migrate_db.py upgrade head

# 5. Verify setup
python scripts/migrate_db.py current

Why PostgreSQL?

• Lower latency (no network overhead for local development)

• Full SQL support with JOINs and complex queries

• Built-in ACID transactions

• Mature ecosystem (pg_dump, psql, GUI tools)

• Lower cost for read-heavy workloads

Migration Helper Script Benefits:

The scripts/migrate_db.py helper script:

• Automatically loads your .env file

• Validates all required environment variables

• Finds alembic.ini in your installed actingweb package

• Provides simple commands: upgrade, downgrade, current, history

• Works with both pip and poetry installations

Common Migration Commands:

python scripts/migrate_db.py upgrade head    # Apply all pending migrations
python scripts/migrate_db.py current         # Show current version
python scripts/migrate_db.py downgrade -1    # Rollback one migration
python scripts/migrate_db.py history         # Show migration history

Alternative: Manual Migration (Not Recommended)

If you prefer to run alembic directly without the helper script:

python -c "import actingweb; from pathlib import Path; print(Path(actingweb.__file__).parent / 'db' / 'postgresql')" | xargs -I{} alembic -c {}/alembic.ini upgrade head

Notes:

• PostgreSQL requires running Alembic migrations before first use (unlike DynamoDB which auto-creates tables)

• For native PostgreSQL: brew install postgresql (macOS) or apt install postgresql (Ubuntu)

• Connection pooling is automatic (psycopg3 with configurable min/max connections)

• Use Docker Compose for multi-service setups (see PostgreSQL Migration Guide)

Choosing a Framework

• Flask: smallest dependency footprint; great for simple apps

• FastAPI: async support and automatic OpenAPI docs at /docs

Web UI and Dev Endpoints

• Enable the web UI with .with_web_ui(True) (available at /<actor_id>/www)

• Enable dev/test helpers with .with_devtest(True) (disable in production)

Running Locally

• Flask: call aw.integrate_flask(flask_app) and run flask_app.run()

• FastAPI: call aw.integrate_fastapi(api) and run uvicorn app:api –reload –port 5000