ops: deploy bring-up checklist (Fly + Neon + R2 + 1Password)

[ericelizes]

Operational steps that need a real shell session. Each item is independent — knock them off in any order. All commands assume cd /home/eric/code/agentclip-app unless noted.

1. Refresh gh token to allow workflow pushes (blocks U19/U20)

gh auth refresh -s workflow

This unblocks pushing .github/workflows/*.yml files. Once done, ping me and I'll ship U19 (api-ci + web-ci GitHub Actions) and U20 (Lighthouse CI gate).

2. Confirm 1Password vault item exists

In 1Password, create item agentclip in vault Personal with these fields:

• DJANGO_SECRET_KEY — python -c "import secrets; print(secrets.token_urlsafe(50))"
• DATABASE_URL — the Neon connection string with ?sslmode=require
• R2_ACCESS_KEY_ID — Cloudflare R2 token id
• R2_SECRET_ACCESS_KEY — Cloudflare R2 token secret
• R2_BUCKET — the bucket name (e.g. agentclip-media)
• R2_ENDPOINT — https://<account-id>.r2.cloudflarestorage.com
• R2_PUBLIC_HOST — cdn.agentclip.dev (the Cloudflare Worker route fronting R2)
• WEB_DEPLOY_PLACEHOLDER — any value; satisfies the placeholder field in bin/.env.web.template

(Field names are referenced verbatim in bin/.env.api.template and bin/.env.web.template.)

3. Bootstrap Fly apps (one-time)

fly auth login
fly apps create agentclip-api
fly apps create agentclip-web

4. Push secrets from 1Password to Fly's vault

eval $(op signin)        # if not already
bin/sync-secrets.sh api
bin/sync-secrets.sh web

5. First deploy

cd api && fly deploy --remote-only
cd ../web && fly deploy --remote-only

Each takes 2–5 minutes. The Django container runs manage.py migrate on startup, so the Neon DB will be schema-applied automatically.

6. Custom domains + SSL

fly certs add agentclip.dev --app agentclip-web
fly certs add www.agentclip.dev --app agentclip-web
fly certs add api.agentclip.dev --app agentclip-api

7. Cloudflare DNS

For each subdomain, add an A/AAAA record pointing at the Fly app hostname (fly ips list --app <app> shows the v4 + v6 IPs):

Domain	Target	Proxy
agentclip.dev	agentclip-web Fly IPs	Proxied (orange cloud)
www.agentclip.dev	same	Proxied
api.agentclip.dev	agentclip-api Fly IPs	Proxied
cdn.agentclip.dev	R2 bucket via Worker route	(Cloudflare Worker, separate setup)

8. Seed the gallery on prod

fly ssh console --app agentclip-api --command 'python manage.py seed_gallery'

9. Smoke test

curl -s -o /dev/null -w '%{http_code}\n' https://agentclip.dev/                                    # 200
curl -s -o /dev/null -w '%{http_code}\n' https://api.agentclip.dev/api/schema/                    # 200
curl -s -o /dev/null -w '%{http_code}\n' https://api.agentclip.dev/api/v1/gallery/                # 200
curl -s -o /dev/null -w '%{http_code}\n' https://agentclip.dev/install.md                          # 200, text/markdown

10. Final cutover

• Tag v0.1.0 on platform: git tag -a v0.1.0 -m 'v0.1.0' && git push --tags
• Tag v0.1.0 on SDK: same in agentclip-python
• Publish SDK to PyPI: cd ~/code/agentclip && uv build && uv publish
• Optional: drop the agentclip.dev URL into the README hero badge so the live demo is one click from GitHub.

---

This issue tracks the operational bring-up. Code-side work continues on main and lands via PR / direct push.

[ericelizes]

✅ Local end-to-end verification (2026-05-06)

First time we've actually proved the platform works as a system, not just as unit tests. All 13 end-to-end paths green against localhost:8000 (api) + localhost:3030 (web).

One-shot repro

Open two terminals.

Terminal 1 (api):

cd ~/code/agentclip-app/api
DJANGO_DEBUG=1 python manage.py migrate --noinput
DJANGO_DEBUG=1 python manage.py runserver 8000

Terminal 2 (web):

cd ~/code/agentclip-app/web
AGENTCLIP_API_URL=http://localhost:8000 \
  NEXT_PUBLIC_AGENTCLIP_API_URL=http://localhost:8000 \
  pnpm dev --port 3030

Terminal 3 (smoke):

cd ~/code/agentclip-app

# 1. create
CREATE=$(curl -s -X POST http://localhost:8000/api/slideshow/ \
  -H 'Content-Type: application/json' \
  -d '{"title":"smoke","description":"e2e","created_by":"Eric Elizes"}')
echo "$CREATE" | python3 -m json.tool

SHARE_TOKEN=$(echo "$CREATE" | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['share_url'].rstrip('/').split('/')[-1])")
WRITE_TOKEN=$(echo "$CREATE" | python3 -c "import json,sys;print(json.load(sys.stdin)['write_token'])")
EDIT_TOKEN=$(echo "$CREATE" | python3 -c "import json,sys;print(json.load(sys.stdin)['edit_url'].split('?t=')[1])")
SLIDESHOW_ID=$(echo "$CREATE" | python3 -c "import json,sys;print(json.load(sys.stdin)['id'])")

# 2. add a slide (real PNG)
python3 -c "from PIL import Image; Image.new('RGB',(640,360),'darkred').save('/tmp/smoke.png')"
curl -s -X POST "http://localhost:8000/api/slideshow/$SLIDESHOW_ID/slides/" \
  -H "Authorization: Bearer $WRITE_TOKEN" \
  -F "media=@/tmp/smoke.png" -F "caption=login screen on staging." | python3 -m json.tool

# 3. open the live pages
echo "viewer: http://localhost:3030/s/$SHARE_TOKEN"
echo "edit:   http://localhost:3030/s/$SHARE_TOKEN/edit?t=$EDIT_TOKEN"
echo "OG:     http://localhost:3030/s/$SHARE_TOKEN/opengraph-image"

What was verified

#	Path	Result
1	POST /api/slideshow/	201 with id, share_url, edit_url, write_token
2	POST /api/slideshow/<id>/slides/	201 with media_url + position
3	GET /api/v1/slideshow/<token>/	200 with slideshow + slides array
4	GET /api/v1/gallery/	200 (empty, as expected — nothing curated locally)
5	PATCH .../slides/1/caption/ (edit_token)	200 with updated caption
6	PATCH ... with WRONG edit_token	401 (auth boundary holds)
7	DELETE .../slides/1/ (edit_token)	204 (slide gone, confirmed via re-GET)
8	GET / (home)	200, 79 KB
9	GET /install.md	200, text/markdown; charset=UTF-8
10	GET /s/<token> (viewer)	200, contains title + caption + "Filed by"
11	GET /s/<token>/edit?t=<edit_token>	200, contains "Edit mode" + editable caption
12	GET /s/<token>/edit (no t param)	404 (security boundary holds)
13	GET /s/<token>/opengraph-image	200, real 1200×630 PNG (18 KB)

What's still unverified

• Cloudflare R2 storage path — local smoke uses Django's FileSystemStorage. The R2 wiring in settings.py only activates when R2_ACCESS_KEY_ID is set; first prod deploy will be the first real test.
• Neon Postgres — local smoke uses sqlite. Same story; the first prod deploy proves the migration path on Postgres.
• CDN custom domain (cdn.agentclip.dev) — needs Cloudflare Worker setup before media URLs resolve under our domain.

These three are deploy-time validations. Everything that runs in the app process is now proven.

[ericelizes]

⚠️ Updated: Redis is now required for rate limits

Commit d342ca2 made the per-IP rate limits actually work — Redis-backed counters + trusted-proxy IP resolution (CF-Connecting-IP > X-Forwarded-For > REMOTE_ADDR).

This adds two extra steps to the deploy bring-up checklist:

2a. Provision Upstash Redis on Fly

# Either via fly's marketplace:
fly redis create
# Or directly with Upstash; both produce a rediss:// URL.

Note the URL — looks like rediss://default:xxx@host.upstash.io:6379.

2b. Add REDIS_URL to 1Password

Drop the URL into the agentclip item in vault Personal as the field REDIS_URL (matches the reference in bin/.env.api.template).

After that, bin/sync-secrets.sh api pushes it to the Fly vault along with the rest of the secrets in step 4.

Verification (after deploy)

The new tests catch the regression in CI / locally, but to verify in prod:

# Hit the create endpoint 21 times from a single CF-Connecting-IP:
for i in $(seq 1 21); do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -H 'CF-Connecting-IP: 198.51.100.99' \
    -H 'Content-Type: application/json' \
    -d "{\"title\":\"spam-$i\"}" \
    https://api.agentclip.dev/api/slideshow/
done
# Expect: ten 201s, ten 201s, then 429 on the 21st.

Without REDIS_URL set, the limit appears per-process (so 2× workers × 2× machines = 80 before 429 hits). With it, the limit is shared and the 21st request is consistently rejected.