Local Deploy

Before You Change Anything

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 agent-runtime).

1

Step 1

Verify working tree

Checks that the working tree is clean and all commits are pushed. Skipped for docs, website, and agent-runtime.

2

Step 2

Build the image

Builds the image locally. The platform and agent-runtime components use ko (no Dockerfile needed — Go binary compiled on your machine). The auth-filter uses Docker (TinyGo/WASM).

3

Step 3

Push to DOCR

Pushes the image to registry.digitalocean.com/crawbl/.

4

Step 4

Update crawbl-argocd-apps

Patches the image tag in the matching component values in crawbl-argocd-apps and commits the change.

5

Step 5

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.

6

Step 6

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.yaml
• components/metacontroller/resources/userswarm-webhook.yaml
• components/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, agent-runtime — deploy those individually):

crawbl app deploy all

Agent Runtime

The Agent Runtime is deployed locally via crawbl app deploy agent-runtime. CI in crawbl-agent-runtime 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 agent-runtime

The git guard is skipped — working tree does not need to be clean. Use --tag only to pin a specific existing image tag.

CLI Quick Reference

Auto-semver applies — no manual tag needed:

crawbl app deploy platform        # deploy platform
crawbl app deploy auth-filter
crawbl app deploy agent-runtime
crawbl app deploy docs
crawbl app deploy website

Use crawbl app build platform 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
Override tag explicitly	crawbl app deploy platform --tag v1.2.3
Deploy Agent Runtime	crawbl app deploy agent-runtime

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