Local Deploy
These steps can affect shared dev workloads or the GitOps control layer. Confirm the target repo, environment, and intended owner before mutating anything.
crawbl app deploy is the standard deployment workflow. CI does not build or push images — all deployments originate locally.
Prerequisites
Log in to the DigitalOcean Container Registry:
doctl registry login
This authenticates Docker with registry.digitalocean.com/crawbl/. The token expires periodically — re-run if you get authentication errors.
Deploy a Component
crawbl app deploy <component> handles the full cycle in one command. The tag is auto-calculated from conventional commits — --tag is optional. The working tree must be clean and fully pushed before deploying (skipped for docs, website, and zeroclaw).
Verify working tree
Checks that the working tree is clean and all commits are pushed. Skipped for docs, website, and zeroclaw.
Build the Docker image
Builds the image locally using the component's Dockerfile (Go binary compiled on your machine for the platform component).
Push to DOCR
Pushes the image to registry.digitalocean.com/crawbl/.
Update crawbl-argocd-apps
Patches the image tag in the matching component values in crawbl-argocd-apps and commits the change.
Create Git tag and GitHub release
Creates a Git tag (auto-calculated from conventional commits; bumps patch if tag exists on remote). Publishes a GitHub release with notes enriched by the local claude CLI (sonnet model) and a full changelog link.
Push and let ArgoCD sync
Pushes the apps repo commit. ArgoCD detects the Git change and rolls the new image into the cluster.
Components
Platform
The crawbl-platform image contains the orchestrator, userswarm webhook, migrate, backup, and reaper entrypoints:
crawbl app deploy platform
This updates image references in crawbl-argocd-apps for:
components/orchestrator/chart/values.yamlcomponents/metacontroller/resources/userswarm-webhook.yamlcomponents/metacontroller/resources/e2e-reaper-cronjob.yaml
Auth Filter
The auth filter is a TinyGo WASM module:
crawbl app deploy auth-filter
This updates components/envoy-gateway/resources/envoy-extension-policy.yaml.
Documentation Site
crawbl app deploy docs
This builds the Docusaurus site and deploys to Cloudflare Pages via wrangler. No Docker or ArgoCD involved.
Website
crawbl app deploy website
This builds the Next.js static site and deploys to Cloudflare Pages via wrangler. No Docker or ArgoCD involved.
All Standard Components
Deploy platform + auth-filter in one call (excludes docs, website, zeroclaw — deploy those individually):
crawbl app deploy all
ZeroClaw
ZeroClaw is deployed locally via crawbl app deploy zeroclaw. CI in crawbl-zeroclaw is disabled.
Tags use the fork convention v<upstream>-crawbl.<N> (e.g. v0.6.5-crawbl.3). The N suffix auto-increments — no --tag needed for normal deploys.
crawbl app deploy zeroclaw
The git guard is skipped — working tree does not need to be clean. Use --tag only to pin a specific existing image tag.
Makefile Shortcuts
The Makefile uses auto-semver — no manual tag needed:
make deploy-dev # deploy platform + auth-filter
make deploy-platform
make deploy-zeroclaw
make deploy-docs
make deploy-website
Use make build-dev to build the platform image without deploying (useful for local testing before pushing).
Quick Reference
| Task | Command |
|---|---|
| DOCR login | doctl registry login |
| Deploy platform | crawbl app deploy platform |
| Deploy auth filter | crawbl app deploy auth-filter |
| Deploy docs | crawbl app deploy docs |
| Deploy website | crawbl app deploy website |
| Deploy platform + auth-filter | crawbl app deploy all |
| Deploy all (auto-semver) | make deploy-dev |
| Override tag explicitly | crawbl app deploy platform --tag v1.2.3 |
| Deploy ZeroClaw | crawbl app deploy zeroclaw |
DOCR Login Troubleshooting
If docker push fails with an authentication error:
# Re-authenticate
doctl registry login
# Verify access
doctl registry repository list-v2
If doctl registry login fails, ensure your DIGITALOCEAN_TOKEN is valid:
set -a && source .env && set +a
doctl auth init --access-token $DIGITALOCEAN_TOKEN
doctl registry login
What's next: Verify Deployment