diff --git a/docs/webhook-auto-deploy.html b/docs/webhook-auto-deploy.html new file mode 100644 index 0000000..ae10154 --- /dev/null +++ b/docs/webhook-auto-deploy.html @@ -0,0 +1,173 @@ + + + + + +Automatic Deploys — Forgejo → Coolify (FleetOps / FleetNow) + + + +
+
+ + FLEETOPS +
+

Operations runbook · Automatic deploys via Forgejo → Coolify webhooks

+ +

Automatic deploys: push → live

+

+ Every Coolify app (FleetOps + FleetNow, staging & prod) deploys automatically on a + git push. The chain is: +

+ 
git push  →  Forgejo webhook  →  Coolify rebuilds the app whose branch matches  →  Traefik serves the new container
+

+ Each Coolify application tracks one branch. A push to that branch fires the webhook; + Coolify rebuilds only the app(s) bound to the pushed branch. So staging pushes + deploy the *.fivetitude.com apps, and main merges deploy the + *.rahamafresh.com (prod) apps. +

+ +
+ Prerequisites on the Coolify app before the webhook will do anything: + +
+ +

Part A — Get the webhook URL + secret from Coolify

+
+
    +
  1. Open the application in Coolify.
    2. +
  2. Confirm Configuration → Advanced → Auto Deploy is ON.
    3. +
  3. Go to the app's Webhooks tab → Manual Git Webhooks → + the Gitea section (Forgejo is Gitea-compatible).
    4. +
  4. Copy the Webhook URL (e.g. + https://<coolify-domain>/webhooks/source/gitea/events/manual) + and the Webhook Secret.
    5. +
+
+ +

Part B — Add the webhook in Forgejo

+
+
    +
  1. Open the repo → Settings → Webhooks → Add Webhook → Forgejo/Gitea.
    2. +
  2. Fill in: + + + + + + + + + +
    FieldValue
    Target URLthe Coolify Webhook URL (Part A)
    HTTP MethodPOST
    POST Content Typeapplication/json
    Secretthe Coolify Webhook Secret (must match exactly)
    Trigger OnPush Events (or Custom → Push only)
    Branch filterthe app's branch (staging or main) — optional but tidy
    Activechecked
    +
    3. +
  3. Click Add Webhook.
    4. +
+
+ +

Part C — Verify the delivery

+
+
    +
  1. In Forgejo, go to repo → Settings → Webhooks. Each webhook shows a status dot: + green = last delivery OK, red = failed.
    2. +
  2. Click the webhook to open its page, then click Test Delivery (top-right).
    3. +
  3. Scroll to Recent Deliveries. Click a delivery row to expand it → + open the Response tab → the HTTP status is there. + 2xx = good.
    4. +
  4. Confirm a deployment started in the Coolify app's Deployments list.
    5. +
  5. Real test: push a trivial change to the branch and confirm only the matching app redeploys.
    6. +
+
+ +

Multiple environments (staging + prod)

+

+ There is one Coolify app per environment, each on its own branch, and + each app has its own webhook secret. Add a separate Forgejo webhook per app + (same repo), each with its own URL/secret and branch filter: +

+ + + + + + +
AppDomainBranch
FleetOps stagingfleetops.fivetitude.comstaging
FleetOps prodfleetops.rahamafresh.commain
FleetNow stagingfleetnow.fivetitude.comstaging
FleetNow prodfleetnow.rahamafresh.commain
+

Promotion: feature → staging (auto-deploys staging) → main (auto-deploys prod).

+ +

Troubleshooting

+ + + + + + + + +
SymptomCause & fix
Delivery 2xx but no deployAuto Deploy off. Turn it on at Configuration → Advanced → Auto Deploy.
Delivery 401 / 403Secret mismatch — re-copy the Coolify secret into the Forgejo webhook's Secret field.
Delivery 404 / 502 on the webhookWrong Target URL, or Coolify unreachable.
Site returns 502Coolify "Ports Exposes" ≠ container port. Set it to 80 and redeploy.
Site returns 503 / self-signed certNo healthy backend yet, or the domain doesn't match the Traefik rule (often a domain typo). Fix the domain and redeploy.
Deploys, but it's the wrong codeWrong branch. Set the app's Branch (e.g. staging) in the Source config, Save, then redeploy (Force rebuild).
+ +
+ Never point a prod app at a non-prod branch. The prod apps + (*.rahamafresh.com) must stay on main. Pointing one at staging + would push unreviewed code to the client's live site. +
+ + +
+ +