Skip to content

Check your SEO health in minutes with my new Tool. Ensure correct on-page Seo on your site Run a free audit →

Quick search
DevOps guide

What "deployed" actually means

A deployment is done when every claim has a command that proves it. This page is the contract the rest of the guide implements.

draft guide-2026.11-draft kit-v0.0.0 markdown

By the end of this page you have a shared definition of done. Every later page is an implementation of this contract, and an agent that can state this contract back to you before touching the box is already safer than most production pipelines.

The goal of this guide is specific. A repository goes in, a URL comes out. The URL is served through Cloudflare, the origin accepts only Cloudflare traffic, the TLS is real, a bot filter sits in front, the deploy is repeatable, a rollback exists, the database has a backup that was actually restored once, and the next agent can read the docs and do it again without asking you twenty questions.

That is the whole game. Everything else is implementation detail.

The shape of the system

Every app in this guide follows the same path in and out.

                        ┌──────────────────────────────┐
   user, crawler, LLM   │  Cloudflare                  │  DNS, TLS, WAF, cache,
   ───────────────────► │  (proxy, Access, cache)      │  bot management, Access
                        └──────────────┬───────────────┘
                                       │  Cloudflare IP ranges only
                                       ▼
                        ┌──────────────────────────────┐
                        │  Traefik v3  :80 / :443      │  one public door for
                        │  forwardedHeaders trusted    │  every app on the box
                        └──────────────┬───────────────┘
                                       │  global middleware crowdsec@file
                                       ▼
                        ┌──────────────────────────────┐
                        │  CrowdSec  LAPI + agent      │  decisions stream,
                        │  bouncer plugin + AppSec     │  captcha-first remediation
                        └──────────────┬───────────────┘
                                       ▼
                        ┌──────────────────────────────┐
                        │  app containers (compose)    │
                        │  web, worker, scheduler,     │
                        │  db, redis, nightwatch,      │
                        │  db_backup                   │
                        └──────────────┬───────────────┘
                                       │  bind mounts on the host
                                       ▼
                        ┌──────────────────────────────┐
                        │  host: Docker, Tailscale,    │
                        │  firewall, backups, disk     │
                        └──────────────────────────────┘

And the path a release takes:

git tag vX.Y.Z
   │
   ▼
CI (Crow CI or GitHub Actions)
   ├── install deps, build assets once
   ├── run tests and static analysis
   ├── build one image per role (web, worker), per architecture
   ├── push immutable tag vX.Y.Z-web / vX.Y.Z-worker + mutable web / worker
   └── deploy step: scp compose + deploy.sh to the host, run deploy.sh
                                     │
                                     ▼
host deploy.sh: preflight -> pull -> maintenance -> recreate -> migrate
                -> health gate -> notify -> rollback if anything fails

The pipeline never builds on the production host. The host never needs Composer, Node, or a compiler. That single rule removes most deploy failures before they can happen.

The six planes

Keep these separate in your head. Each one can fail independently, and each one has a chapter.

  1. The edge. Cloudflare owns DNS, TLS, caching, WAF, and optional Access. The origin must be unreachable except from Cloudflare and your tailnet. If the origin is reachable directly, half of the edge is decoration.
  2. The door. One Traefik instance terminates TLS, applies the global CrowdSec middleware, and routes by Host() label. No app publishes its own port to the internet.
  3. The defense. CrowdSec watches Traefik logs and AppSec, keeps a decisions stream, and asks the bouncer to serve a captcha or a ban. Whitelists keep your own infrastructure out of it.
  4. The runtime. Docker Compose with one process per container: web, worker, scheduler, database, cache, monitoring agent, backup sidecar. Bind mounts for state. Memory limits on everything.
  5. The delivery. A git host, a CI system, a private registry, immutable tags, and a pull-only deploy script with a health gate and a rollback path.
  6. The data and the ops. Backups that restore, alerts that fire, logs that survive, secrets that rotate, and docs that let the next agent operate without you.

The definition of done

An app is deployed when all of the following are true at the same time. Not most of them. All of them.

  • https://app.example.com returns the expected status through Cloudflare.
  • The same request to ${VPS_IP} with Host: app.example.com fails to connect, because the origin firewall allows only Cloudflare and the tailnet.
  • The origin certificate is issued by Let's Encrypt or Cloudflare Origin CA, not TRAEFIK DEFAULT CERT.
  • Traefik routes the host, applies CrowdSec, and exposes no dashboard or metrics to the public internet.
  • CrowdSec is running, the bouncer polls the decisions stream, and your own IPs are whitelisted with a canary that proves the whitelist still discriminates.
  • The app runs as one image per role, pinned by an immutable tag, with /up returning 2xx.
  • A redeploy of the same tag is a no-op and says so. A failed deploy never leaves the site in maintenance mode.
  • deploy.sh --rollback (or an equivalent documented procedure) works.
  • Migrations are idempotent and were tested against the same database engine as production.
  • A database backup exists from today, was restored into a throwaway container at least once, and a staleness alert would fire if it stopped.
  • Nightwatch (or an equivalent) shows no new exceptions after the deploy.
  • No secrets live in git, in image layers, or in world-readable files.
  • The docs describe how to deploy, roll back, restore, and where the credentials live.

Print that list. Put it in DEPLOY.md at the top. Make it the first thing an agent reads.

Ten principles

These are the opinions this guide is built on. They save time because they remove decisions.

  1. One public door. Every app on a box goes through one Traefik instance. No app publishes port 80 or 443 directly.
  2. Cloudflare only at the origin. The origin firewall allows Cloudflare ranges plus the tailnet. Nothing else. If you skip this, the WAF, bot management, and cache are optional for attackers.
  3. Immutable images, mutable pointers. Builds produce vX.Y.Z-web and vX.Y.Z-worker. Deploy scripts move web and worker pointers, rollbacks pin the immutable tag. Never deploy latest blindly.
  4. Build once, not per environment. Assets and dependencies compile in CI, once per release. The same bytes that passed tests are the bytes that run.
  5. Build on the CI runner, never on the production host. Production pulls images. It does not compile PHP, install Node, or run Composer.
  6. Configuration lives outside the image. Env files on the host, secrets from a manager or mode 600 files. A rebuild of the same tag with different config is a deploy, not a code change.
  7. State on bind mounts you can see. ./.storage, ./.postgres-db, ./backups. Named volumes are fine for caches you can lose. If losing it would hurt, it is a bind mount with a backup.
  8. Fail loudly, especially when nothing happened. A deploy that silently changed nothing is a bug. A backup that has not written a file in a month is an incident. A health check that returns 200 while the app 500s is not a health check.
  9. Security first with a human fallback. Captcha before ban. Whitelist yourself. Keep a second way in (tailnet SSH, provider console). Assume one layer will fail open.
  10. Document the failure, not just the fix. Every incident becomes three lines in the runbook and one entry in the failure-modes table. Future agents only learn from what is written down.

The agent operating loop

An agent should not improvise infrastructure. It should run this loop, and each page of this guide ends with the verification step of the loop.

  1. Collect facts. Host, IP, domain, registry, repo, image roles, ports, database engine, secret source, backup target, whether the origin is already firewalled. Ask, do not guess.
  2. Write the plan. Ordered list of changes with a verification command after each. One change per deploy.
  3. Implement in dependency order. Box, edge, ingress, security, runtime, delivery, data, backups, observability. Never the other way around: an exposed app with no firewall and no monitoring is not a deploy, it is an incident waiting for a timestamp.
  4. Verify externally. Curl the real URL through Cloudflare, curl the origin directly, check the dashboard from the tailnet, check the certificate issuer, check the logs. Internal checks lie.
  5. Document. Update DEPLOY.md, add the tag to the changelog, write the rollback line. If something surprised you, write an AAR.

Silent failure patterns this guide exists to prevent

Every one of these happened on a real production box, most of them twice.

  • The CI run was green but the deploy step never ran, because a hostname did not resolve inside a build container.
  • /up returned 200 while a key endpoint returned 500, because the health route touches no dependencies.
  • The backup sidecar kept retrying forever after a compose project rename changed a container hostname.
  • The public dashboard and a public /metrics endpoint sat open for months because an internal router was enabled on the public entrypoint.
  • The origin served a self-signed default certificate for months while Cloudflare was set to Full, not Full strict.
  • A rotated API key in the secret manager never reached the host env file, and a background job broke for twelve days.
  • The whitelist was widened during an incident and never narrowed, so an internal crawler skipped bot protection on every host.
  • A repo had tens of gigabytes of git data and no database dump, and every clone in the fleet was a copy, not a backup.

When you read a chapter, ask which of these it prevents. If a chapter does not prevent one, it is probably optional complexity.

How to use this guide

Chapters are ordered by dependency, but you can deploy an app by following only what you need. The companion kit in kit/ contains the configs used in the pages, sanitized and parameterized. Start with kit/README.md if you want files instead of prose.

Version baseline used throughout: Traefik 3.6, CrowdSec 1.8, Docker 29, Forgejo 17, Crow CI 6.12, PHP 8.5, Laravel 13, PostgreSQL 18, MySQL 8.2. Pin everything you can, especially base images, and read the failure modes before upgrading any of them.

Failure modes

  • Contract theater. The agent repeats the principles but never runs the proof commands. Fix: require the proof table from chapter 14 before accepting a deployment.
  • Plane mixing. Firewall, ingress, and app config changed in one step. Fix: one plane per change, verification after each.
  • Skipped intake. The agent starts from the repo and invents the domain or database engine. Fix: the intake checklist in appendix C is a hard gate.

Checklist

  • The definition of done is copied into the repo or task
  • The six planes are named and owned
  • The fact sheet is complete
  • The proof commands are known before implementation starts
  • The next chapter is chosen by dependency order, not by convenience

One last thing. The most valuable output of a deployment is not the running container. It is the documented, repeatable path that produced it, because that is the thing the next agent can follow.

Proof you are done

  • - Restate the definition of done in its own words, naming at least eight of the fourteen proof points.
  • - Draw the request path: Cloudflare, Traefik, CrowdSec, app, data.
  • - Name the six planes and which chapter owns each one.
  • - State the facts it still needs (server, domain, registry, image roles, database, secret source, backup target).
  • - Name the verification command it will run after the next change, before making the change.

Subscribe to the newsletter

One email when new articles are published. No spam, unsubscribe anytime.

Protected by Mailcoach. Double opt-in may apply.