AWS least-privilege idempotent deployment

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv pip install --system ruff
+      - run: ruff check src/ server/src/ tools/ tests/ server/tests/
+
+  test-client:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv pip install --system -e ".[dev]"
+      - run: pytest tests/ -v --tb=short
+
+  test-server:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: etelemetry
+          POSTGRES_PASSWORD: testpassword
+          POSTGRES_DB: etelemetry_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DATABASE_URL: postgresql+asyncpg://etelemetry:testpassword@localhost:5432/etelemetry_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.11"
+      - run: uv pip install --system -e "./server[dev]"
+      - run: pytest server/tests/ -v --tb=short -k "not test_migration"
+
+  validate-infra:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: opentofu/setup-opentofu@v1
+      - name: Validate OpenTofu
+        working-directory: infra
+        run: |
+          tofu init -backend=false
+          tofu validate
+          tofu fmt -check -recursive
+      - name: Run IAM policy tests
+        run: |
+          pip install pytest
+          pytest infra/tests/test_iam_policy.py -v

.github/workflows/deploy.yml

@@ -0,0 +1,123 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "server/**"
+      - "src/**"
+      - "deploy/**"
+      - "infra/scripts/**"
+      - ".github/workflows/deploy.yml"
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false  # Queue, don't cancel
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: production
+      url: https://et.dandiproject.org
+    steps:
+      - uses: actions/checkout@v4
+
+      # Authenticate to AWS via OIDC — no access keys needed
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: ${{ vars.AWS_DEPLOY_ROLE_ARN }}
+          aws-region: ${{ vars.AWS_REGION || 'us-east-1' }}
+
+      # Build and push Docker image to ECR
+      - name: Login to ECR
+        id: ecr-login
+        uses: aws-actions/amazon-ecr-login@v2
+
+      - name: Build and push image
+        env:
+          ECR_REGISTRY: ${{ steps.ecr-login.outputs.registry }}
+          ECR_REPOSITORY: etelemetry
+          IMAGE_TAG: ${{ github.sha }}
+        run: |
+          docker build -f deploy/Dockerfile -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
+          docker tag $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG $ECR_REGISTRY/$ECR_REPOSITORY:latest
+          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
+          docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest
+
+      # Deploy via SSM (no SSH needed)
+      - name: Get instance ID
+        id: instance
+        run: |
+          INSTANCE_ID=$(aws ec2 describe-instances \
+            --filters "Name=tag:Name,Values=etelemetry" "Name=instance-state-name,Values=running" \
+            --query 'Reservations[0].Instances[0].InstanceId' \
+            --output text)
+          echo "id=$INSTANCE_ID" >> "$GITHUB_OUTPUT"
+
+      - name: Deploy via SSM
+        env:
+          ECR_REGISTRY: ${{ steps.ecr-login.outputs.registry }}
+          INSTANCE_ID: ${{ steps.instance.outputs.id }}
+        run: |
+          COMMAND_ID=$(aws ssm send-command \
+            --instance-ids "$INSTANCE_ID" \
+            --document-name "AWS-RunShellScript" \
+            --parameters "commands=[\"bash /opt/etelemetry/infra/scripts/deploy.sh ${{ github.sha }} ${ECR_REGISTRY}/etelemetry ${{ vars.AWS_REGION || 'us-east-1' }}\"]" \
+            --timeout-seconds 300 \
+            --query 'Command.CommandId' \
+            --output text)
+
+          echo "SSM Command ID: $COMMAND_ID"
+
+          # Poll for completion
+          for i in $(seq 1 60); do
+            STATUS=$(aws ssm get-command-invocation \
+              --command-id "$COMMAND_ID" \
+              --instance-id "$INSTANCE_ID" \
+              --query 'Status' \
+              --output text 2>/dev/null || echo "Pending")
+
+            case "$STATUS" in
+              Success)
+                echo "Deployment successful!"
+                aws ssm get-command-invocation \
+                  --command-id "$COMMAND_ID" \
+                  --instance-id "$INSTANCE_ID" \
+                  --query 'StandardOutputContent' \
+                  --output text
+                exit 0
+                ;;
+              Failed|TimedOut|Cancelled)
+                echo "Deployment FAILED with status: $STATUS"
+                aws ssm get-command-invocation \
+                  --command-id "$COMMAND_ID" \
+                  --instance-id "$INSTANCE_ID" \
+                  --query 'StandardErrorContent' \
+                  --output text
+                exit 1
+                ;;
+              *)
+                sleep 5
+                ;;
+            esac
+          done
+
+          echo "Deployment timed out waiting for SSM command"
+          exit 1
+
+      # Verify deployment
+      - name: Health check
+        run: |
+          sleep 10
+          curl -sf https://et.dandiproject.org/ || {
+            echo "Health check failed!"
+            exit 1
+          }
+          echo "Deployment verified at https://et.dandiproject.org/"

.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # Trusted publishing via OIDC
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for hatch-vcs
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/etelemetry
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          # Get previous tag
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -z "$PREV_TAG" ]; then
+            NOTES=$(git log --oneline --no-merges)
+          else
+            NOTES=$(git log --oneline --no-merges "${PREV_TAG}..HEAD")
+          fi
+          echo "notes<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$NOTES" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Determine pre-release
+        id: prerelease
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          if echo "$TAG" | grep -qE '(alpha|beta|rc|dev|pre)'; then
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ steps.prerelease.outputs.is_prerelease }}
+          body: |
+            ${{ steps.notes.outputs.notes }}

.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+uv.lock
+
+# Environment / Secrets
+.env
+.env.*
+!.env.example
+!deploy/.env.example
+
+# MaxMind GeoIP databases
+*.mmdb
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Docker
+*.log

.specify/memory/constitution.md

@@ -1,7 +1,9 @@
 <!--
   Sync Impact Report
   ==================
-  Version change: 0.0.0 (template) → 2026.03.22
+  Version change: 2026.03.22 → 2026.03.22.1
+  Previous version ratified: 2026-03-22 (initial)
+  Amendment: Added CI failure resolution requirement to Principle III
   Modified principles: N/A (initial population from template)
   Added sections:
     - Principle I: Isolated Environments
@@ -67,8 +69,9 @@ parallel workers MUST coordinate to avoid file conflicts.
 - Branches MUST be used for features; `main` is protected.
 - Before committing, subagents MUST pull latest changes and resolve
   conflicts rather than force-pushing.
-
-### IV. Test-Driven with Real Use Cases
+- When working with a GitHub repository, tasks MUST ensure that remote
+  CI passes. If CI fails after a push, the failure MUST be diagnosed
+  and fixed before proceeding to the next task.
 
 Every specification MUST conclude with real-use-case validation.
 Tests MUST exercise actual user workflows, not just unit-level mocks.
@@ -188,4 +191,4 @@ verify compliance with these principles.
   constitution, an amendment MUST be proposed rather than working
   around the gap silently.
 
-**Version**: 2026.03.22 | **Ratified**: 2026-03-22 | **Last Amended**: 2026-03-22
+**Version**: 2026.03.22.1 | **Ratified**: 2026-03-22 | **Last Amended**: 2026-03-22

CLAUDE.md

@@ -0,0 +1,30 @@
+# etelemetry Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-03-22
+
+## Active Technologies
+
+- Python 3.11+ + FastAPI, SQLAlchemy 2.0, asyncpg, httpx, geoip2, (001-stack-migration-refactor)
+
+## Project Structure
+
+```text
+backend/
+frontend/
+tests/
+```
+
+## Commands
+
+cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
+
+## Code Style
+
+Python 3.11+: Follow standard conventions
+
+## Recent Changes
+
+- 001-stack-migration-refactor: Added Python 3.11+ + FastAPI, SQLAlchemy 2.0, asyncpg, httpx, geoip2,
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->