Set up development environment (fix Docker build, pin LocalStack, add AGENTS.md)

[whummer]

Summary

Sets up a working development environment for this Flask + Celery + Postgres + Redis + LocalStack template. The documented dev workflow (make develop / Docker Compose) no longer builds or runs on today's registries because of unpinned, drifted dependencies. This PR makes the environment reproducible with minimal, well-commented dependency pins and adds AGENTS.md with cloud-specific run instructions. No application code was changed.

Changes

• Dockerfile — make the image build on the python:3.8-alpine3.11 base:
  • Pin Poetry to 1.1.15 (matches poetry.lock lock-version 1.1; avoids modern Poetry's rapidfuzz source build on musl).
  • Pre-install cryptography==2.8 so Poetry's keyring/SecretStorage dep doesn't pull the latest cryptography (needs Rust + setuptools>=77, impossible on py3.8).
  • poetry config virtualenvs.create false — install into the system interpreter (the venv Poetry seeds ships a setuptools too new to build the 2020-era psycopg2/uwsgi/SQLAlchemy-Utils sdists).
  • Add /home/app/.local/bin to PATH so poetry run flask/celery/uwsgi resolve.
• docker-compose.yaml — pin localstack/localstack:3.8.1. The unpinned/latest tag now requires a paid LOCALSTACK_AUTH_TOKEN and exits (code 55) without one, breaking the /files S3 flow.
• AGENTS.md — new; Cursor Cloud specific instructions (start dockerd manually, use sudo -E docker compose, DEV=true for the dev server, bring-up sequence, the /files bucket-order gotcha, and the dependency-pin rationale).

Verification

All five services build and run via Docker Compose (DEV=true), migrations apply, and both core flows work end to end:

• Counter route / increments a Postgres-backed counter (also driven by the Celery Beat do_something heartbeat every 5s: 513 → 524).
• LocalStack S3: GET /files creates test-bucket and lists it; GET /files/create uploads objects; listing then shows the uploaded objects.

flask_localstack_demo.mp4

Counter page:

Counter page

LocalStack S3 /files JSON listing with uploaded objects:

S3 files listing

• Build: DEV=true sudo -E docker compose build
• Migrate: ... docker compose run --rm worker poetry run flask db upgrade
• Run: DEV=true sudo -E docker compose up -d
• Tests: ... docker compose run --rm worker poetry run pytest (pytest 5.4.1 installed; template ships no tests)

_{To show artifacts inline, enable in settings.}