feat: add Fly deployment template

[vieiralucas]

Summary

• Add deploy/fly/fly.toml with Fly Machines configuration for zopp-server
• Add deploy/fly/README.md with step-by-step deployment instructions
• Configures gRPC on port 50051, health checks on port 8080 (/healthz)
• PostgreSQL via Fly Postgres attach (auto-sets DATABASE_URL)
• TLS handled automatically by Fly's edge — no server-side TLS config needed

Test Plan

• fly.toml ports match server defaults (50051 gRPC, 8080 health)
• Health check path /healthz matches server implementation
• README documents full workflow: launch, postgres, deploy, invite, connect
• No secrets or credentials in template files
• Environment variable documentation matches server implementation

---

Summary by cubic

Adds a Fly.io deployment template for zopp-server with a ready-to-use fly.toml and a step-by-step guide. Completes Story 3.2 by exposing gRPC via Fly’s edge (TLS), adding health checks, and using Fly Postgres via DATABASE_URL.

• New Features

  • Added deploy/fly/fly.toml: gRPC on internal port 50051 behind TLS on 443 (and 80), health checks on 8080 (/healthz), auto start/stop, shared-cpu-1x with 256MB.
  • Config sets primary_region, builds from server.Dockerfile, and defaults ZOPP_EMAIL_VERIFICATION_REQUIRED=false for first-run.

• Docs

  • Added deploy/fly/README.md with launch, Postgres create/attach, deploy, invite via fly ssh, CLI connect (correct --server flag order), scaling, and troubleshooting (fly checks list).

^{Written for commit 8bb47e3. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 7 files

Confidence score: 4/5

• This PR looks safe to merge with minimal risk: both findings are documentation/artifact inconsistencies (severity 5/10) rather than clear runtime code regressions.
• The most impactful issue is in deploy/fly/README.md, where the troubleshooting health check points to the public app URL even though /healthz is on internal port 8080; this can mislead operators during incident triage.
• The mismatch in _bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md appears process/documentation-related (file list not matching repo state), which raises confusion risk more than functional breakage.
• Pay close attention to deploy/fly/README.md and _bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md - align health-check guidance with Fly port exposure and correct the recorded file list.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="deploy/fly/README.md">

<violation number="1" location="deploy/fly/README.md:147">
P2: The troubleshooting health check command targets the public app URL, but this Fly config exposes public ports to gRPC (50051) while `/healthz` is served on internal port 8080. Use an internal check command instead.</violation>
</file>

<file name="_bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md">

<violation number="1" location="_bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md:188">
P2: The File List is inconsistent with the repository state: it says `deploy/fly/fly.toml` and `deploy/fly/README.md` were added, but those files are absent.

(Based on your team's feedback about treating _bmad-output artifacts as planning docs and only flagging repository-state contradictions.) [FEEDBACK_USED]</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[vieiralucas]

@cubic-dev-ai Please do a full re-review of the PR.

[cubic-dev-ai]

@cubic-dev-ai Please do a full re-review of the PR.

@vieiralucas I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

3 issues found across 7 files

Confidence score: 3/5

• There is some merge risk because deploy/fly/fly.toml has health checks under top-level [checks] instead of service-level checks, which can leave unhealthy machines in rotation and impact live traffic.
• deploy/fly/README.md contains a concrete CLI usage error (zopp join with --server in the wrong position), so users following the docs may hit immediate deployment/setup failures.
• _bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md appears out of sync with the repo state by reporting created files that are missing, which raises uncertainty about deployment completeness.
• Pay close attention to deploy/fly/fly.toml, deploy/fly/README.md, and _bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md - health-check behavior, command correctness, and artifact/repo consistency should be corrected before relying on this deployment path.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="deploy/fly/README.md">

<violation number="1" location="deploy/fly/README.md:69">
P2: The `zopp join` example uses `--server` in the wrong position; this invocation will fail to parse. Put `--server` before the subcommand.</violation>
</file>

<file name="_bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md">

<violation number="1" location="_bmad-output/implementation-artifacts/3-2-create-fly-deployment-template.md:188">
P2: The artifact reports `deploy/fly/fly.toml` and `deploy/fly/README.md` as created, but those files are missing from the repository.</violation>
</file>

<file name="deploy/fly/fly.toml">

<violation number="1" location="deploy/fly/fly.toml:36">
P2: Use service-level health checks instead of top-level `[checks]`; otherwise failed health checks won't remove unhealthy machines from request routing.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Use service-level health checks instead of top-level [checks]; otherwise failed health checks won't remove unhealthy machines from request routing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At deploy/fly/fly.toml, line 36:

<comment>Use service-level health checks instead of top-level `[checks]`; otherwise failed health checks won't remove unhealthy machines from request routing.</comment>

<file context>
@@ -0,0 +1,47 @@
+    handlers = ["http"]
+
+# Health checks using the HTTP health endpoint
+[checks]
+  [checks.health]
+    port = 8080
</file context>