App Setup Guide

1. Create AWS account at aws.amazon.com
2. Enable MFA on root account immediately
3. Create IAM user (or use AWS SSO) for daily use — don't use root
4. Install AWS CLI: brew install awscli → aws configure (region: eu-central-1)

emealia does not use Auth0 or any password-based auth. Sign-in is social-only, delegated to the identity provider's OAuth 2.0 Authorization Code flow, exchanged server-side by GoogleAuthBoundary. Local dev/CI default to FakeAuthBoundary — no real credentials needed until a real beta user signs in.

1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID → type "Web application"
2. Authorized redirect URI: https://api.emealia.eu/auth/google/callback (and http://localhost:8000/auth/google/callback for local dev)
3. Note: Client ID, Client Secret → needed in Step 3.2
4. Apple Sign-In (story 7.1b) is not yet built — skip it for beta

1. console.anthropic.com → API Keys → Create key → name: "emealia-beta"
2. Immediately set a spend cap: Settings → Billing → Spend Limit → $50/month
3. Sign DPA (Data Processing Agreement) — required before any EU user data is processed

1. dashboard.stripe.com → Create account → enable test mode
2. Developers → API Keys → note Secret Key (sk_test_…)
3. Install Stripe CLI: brew install stripe/stripe-cli/stripe
4. Stripe Tax: Settings → Tax → Enable (needed for EU VAT + US sales tax)

1. sentry.io → New Project → Python (backend) + Vue (frontend) → note DSN
2. Free tier: 5k errors/month — sufficient for beta

brew install python@3.13 node@24 docker terraform git gh
brew link python@3.13 --force
python3 --version  # must be 3.13.x
node --version     # must be 24.x

git clone https://github.com/enikolae/emealia-app.git
cd emealia-app
cp .env.example .env   # edit with real dev values (see table below)

docker compose up -d db         # PostgreSQL in Docker
cd backend
python3.13 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
alembic upgrade head             # run migrations
uvicorn app.main:app --reload    # → http://localhost:8000
curl http://localhost:8000/health  # should return {"status":"ok"}

cd frontend
npm install
npm run dev    # → http://localhost:5173

cd backend && pytest                    # all unit tests (boundary fakes, no real calls)
cd frontend && npm run test             # Vitest

The API CloudFront distribution needs an HTTPS certificate. CloudFront requires certs in us-east-1 regardless of app region. Request before Terraform (validation takes a few minutes).

# CloudFront certs MUST be in us-east-1 — not eu-central-1
aws acm request-certificate \
  --domain-name api.emealia.eu \
  --validation-method DNS \
  --region us-east-1

# Note the CertificateArn from the output — needed in beta.tfvars
# Then validate via DNS: add the CNAME record shown in ACM console to your DNS
# Wait for status to show "ISSUED" (usually 5-10 min after DNS propagates)

cd infra/aws/bootstrap
terraform init
terraform apply   # creates S3 bucket "emealia-tf-state" + DynamoDB "emealia-tf-lock"

cd infra/aws/envs/beta
cp beta.tfvars.example beta.tfvars
# Edit beta.tfvars — fill in:
#   db_password_initial = "..."  (generate: openssl rand -base64 24)

cd infra/aws/envs/beta
terraform init
terraform plan -var-file=beta.tfvars   # review what will be created
terraform apply -var-file=beta.tfvars  # ~5-8 minutes

Terraform creates: VPC + public/private subnets, NAT instance t4g.nano (route table for private subnets), ECR, Secrets Manager secrets, IAM roles + OIDC provider, RDS PostgreSQL 17 (private subnet), SQS main queue + DLQ, API Lambda + Function URL (IAM-auth), migration Lambda, Worker Lambda + SQS event-source mapping, CloudWatch log groups, and AWS Budgets alert. CloudFront/S3 frontend wiring is the next module/deploy layer.

terraform output   # shows all important values

Go to AWS Console → Secrets Manager. For each secret, click "Retrieve secret value" → "Edit" → set value:

The backend Dockerfile needs one extra line to run FastAPI on Lambda. Confirm it's present before building:

# These lines must be in backend/Dockerfile (after pip install):
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.0 \
  /lambda-adapter /opt/extensions/lambda-adapter
ENV AWS_LWA_PORT=8080
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

# Login (replace ACCOUNT_ID)
aws ecr get-login-password --region eu-central-1 \
  | docker login --username AWS \
    --password-stdin ACCOUNT_ID.dkr.ecr.eu-central-1.amazonaws.com

# Build for ARM (Lambda runs on Graviton) + push
docker buildx build --platform linux/arm64 \
  -t ACCOUNT_ID.dkr.ecr.eu-central-1.amazonaws.com/emealia-beta-backend:latest \
  --push ./backend

# Update API Lambda with the new image
aws lambda update-function-code \
  --function-name emealia-beta-api \
  --image-uri ACCOUNT_ID.dkr.ecr.eu-central-1.amazonaws.com/emealia-beta-backend:latest \
  --region eu-central-1
aws lambda wait function-updated \
  --function-name emealia-beta-api --region eu-central-1

# Update migration Lambda (same image, different CMD set in Terraform)
aws lambda update-function-code \
  --function-name emealia-beta-migrate \
  --image-uri ACCOUNT_ID.dkr.ecr.eu-central-1.amazonaws.com/emealia-beta-backend:latest \
  --region eu-central-1
aws lambda wait function-updated \
  --function-name emealia-beta-migrate --region eu-central-1

# Update worker Lambda (if using same image)
aws lambda update-function-code \
  --function-name emealia-beta-worker \
  --image-uri ACCOUNT_ID.dkr.ecr.eu-central-1.amazonaws.com/emealia-beta-backend:latest \
  --region eu-central-1
aws lambda wait function-updated \
  --function-name emealia-beta-worker --region eu-central-1

# Invoke the migration Lambda once — same image, CMD runs alembic upgrade head
aws lambda invoke \
  --function-name emealia-beta-migrate \
  --region eu-central-1 \
  /tmp/migrate-response.json
cat /tmp/migrate-response.json   # should show {"statusCode": 200}

# Check migration logs in CloudWatch → /emealia/emealia-beta/migrate
aws logs tail /emealia/emealia-beta/migrate --region eu-central-1

GitHub → repo → Settings → Secrets → Actions → add:

No ANTHROPIC_API_KEY GitHub secret — the per-PR AI reviewer workflows were removed on 2026-07-04 (not cost-efficient). The runtime meal-parsing key lives in AWS Secrets Manager (emealia-beta/anthropic), never in GitHub Actions.

# Build Vue PWA
cd frontend && npm run build   # → frontend/dist/

# Add .htaccess to dist/ for SPA routing
cat > frontend/dist/.htaccess <<'EOF'
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>
EOF

# Upload to All-Inkl via FTP (same pattern as deploy.py)
# Target: /app/ or /beta/ directory in your webspace

Point your frontend domain (e.g. beta.emealia.eu) to the All-Inkl directory in the KAS control panel.

Add both records in your DNS provider (KAS or wherever emealia.eu is managed). There is no ALB DNS name in the beta setup. CloudFront should use api_function_url as its /api/* origin and sign requests with SigV4/OAC. ACM validation CNAME must be present for the cert to stay ISSUED.

# API health check through CloudFront → Lambda (should return {"status":"ok"})
curl https://api.emealia.eu/health

# Check Lambda function state
aws lambda get-function-configuration \
  --function-name emealia-beta-api \
  --region eu-central-1 \
  --query '{State:State,LastStatus:LastUpdateStatus,LastError:LastUpdateStatusReason}'

# Watch live API logs
aws logs tail /emealia/emealia-beta/api --follow --region eu-central-1