Development Setup¶

Time to run

Clone, install dependencies, docker compose up -d — the API is available on localhost:9879 in under 5 minutes. Database (RDS) and Redis (ElastiCache) connect to managed AWS services by default; override with local instances via .env for fully offline development.

Prerequisites¶

Tool	Version	Purpose
Python	3.11+	API + Worker runtime
Node.js	20+	Frontend build
Docker	24+	Container builds
Docker Compose	v2+	Local development
AWS CLI	v2	Secrets Manager access

Quick Start¶

1. Clone and Install¶

git clone git@github.com:fullpass-4pass/4pass.git
cd 4pass

# Python dependencies
pip install -r requirements.txt

# Frontend dependencies
cd frontend && npm install && cd ..

2. Docker Compose (Recommended)¶

# Build API image (includes frontend)
docker compose build

# Build worker image (separate optimized build)
docker compose build worker-image

# Start services
docker compose up -d

Services Defined¶

Service	Port	Description
`api`	9879:8000	FastAPI + Vue.js SPA
`worker-image`	—	Build-only (worker Docker image)

Note

Database (RDS) and Redis (ElastiCache) run as managed AWS services even in development. Configure via environment variables or .env file.

3. Initialize Database¶

curl -X POST "http://localhost:9879/setup/fresh-start" \
  -H "Authorization: Bearer $SETUP_API_KEY"

Environment Variables¶

Core¶

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@host:5432/db`
`REDIS_URL`	Redis/Valkey connection string	`redis://host:6379/0`
`JWT_SECRET_KEY`	JWT signing key	`secrets.token_urlsafe(32)`
`SETUP_API_KEY`	Database initialization key	Random string

Encryption¶

Variable	Description	Example
`ENCRYPTION_KEY`	Master encryption key (local mode)	`secrets.token_urlsafe(32)`
`USE_AWS_KMS`	Enable KMS for encryption	`true` / `false`
`FRONTEND_KMS_KEY_ID`	KMS key alias for frontend encryption	`alias/frontend-encryption`

ECS (Production)¶

Variable	Description	Example
`ECS_CLUSTER`	ECS cluster name	`shioaji-cluster`
`ECS_TASK_DEFINITION`	Worker task definition	`shioaji-worker`
`ECS_SUBNETS`	Comma-separated subnet IDs	`subnet-xxx,subnet-yyy`
`ECS_SECURITY_GROUPS`	Worker security group	`sg-xxx`
`ECS_LAUNCH_TYPE`	EC2 or FARGATE	`EC2`
`WORKER_IDLE_TIMEOUT`	Worker idle timeout (seconds)	`1800` (30 min)

Optional¶

Variable	Description	Default
`CAPTCHA_ENABLED`	Enable Cloudflare Turnstile	`false`
`CAPTCHA_SECRET_KEY`	Turnstile secret key	—
`ORDER_TASK_QUEUE_URL`	SQS queue for order tasks	— (falls back to BackgroundTasks)
`WORKER_CONTROL_QUEUE_URL`	SQS FIFO for worker control	—

Project Structure¶

├── app/                         # FastAPI application
│   ├── main.py                  # Entry point, middleware stack
│   ├── core/                    # Auth, crypto, database, Redis
│   ├── models/                  # SQLAlchemy models
│   ├── routers/                 # API endpoints
│   ├── schemas/                 # Pydantic models
│   ├── services/                # Business logic + brokers
│   └── alembic/                 # Database migrations
├── lambda/                      # Lambda functions (5 handlers)
├── backtest/                    # PineScript compiler + backtester
├── frontend/                    # Vue 3 SPA
├── terraform/                   # AWS IaC (~80 resources)
├── scripts/                     # Build scripts (Lambda layer, etc.)
├── docs/                        # This documentation site
├── Dockerfile                   # API multi-stage build
├── Dockerfile.worker            # Worker optimized build (254 MB)
├── docker-compose.yaml          # Local development
├── requirements.txt             # API dependencies
├── requirements-worker.txt      # Worker dependencies
└── mkdocs.yml                   # Documentation config

Database Migrations¶

# Create a new migration
cd app && alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback one step
alembic downgrade -1

Running the Backtester¶

# Run a strategy
python -m backtest --script backtest/strategies/macd_crossover.pine --timeframe 4h

# Without magnifier (faster, less realistic)
python -m backtest --script backtest/strategies/supertrend.pine --timeframe 1h --no-magnify

# JSON output for programmatic use
python -m backtest --script backtest/strategies/rsi_overbought.pine --timeframe 1d --json

Terraform¶

cd terraform

# Initialize
terraform init

# Plan changes
terraform plan -var-file="prod.tfvars"

# Apply
terraform apply -var-file="prod.tfvars"

Production Safety

Always review terraform plan output before applying. The platform manages ~80 AWS resources including ECS clusters, Lambda functions, SQS queues, and IAM roles.