Overview Dex provides a multi-stage deployment pipeline:
Preflight : Validate entries, assets, and catalog integrityRelease publish : Deploy assets and catalog to API endpointsSite deploy : Push site repo to trigger Pages deployment
This guide covers the canonical workflows for test and production environments.
Deployment Architecture ┌─────────────────┐ │ Local Repo │ │ (site) │ └────────┬────────┘ │ │ dex release preflight │ (validate all) ▼ ┌─────────────────┐ │ Release │ │ Publish │ │ - Assets │ │ - Catalog │ │ - Snapshot │ └────────┬────────┘ │ │ dex deploy │ (git push) ▼ ┌─────────────────┐ │ Cloudflare │ │ Pages │ │ (build + cdn) │ └─────────────────┘
Prerequisites Environment Variables Set admin tokens for API authentication:
Test environment: export DEX_ASSETS_ADMIN_TOKEN_TEST = "your-test-assets-token" export DEX_CATALOG_ADMIN_TOKEN_TEST = "your-test-catalog-token"
Production environment: export DEX_ASSETS_ADMIN_TOKEN_PROD = "your-prod-assets-token" export DEX_CATALOG_ADMIN_TOKEN_PROD = "your-prod-catalog-token"
Add these to your shell profile (~/.bashrc, ~/.zshrc) for persistence: echo 'export DEX_ASSETS_ADMIN_TOKEN_PROD="..."' >> ~/.zshrc echo 'export DEX_CATALOG_ADMIN_TOKEN_PROD="..."' >> ~/.zshrc
Worker Secrets Ensure corresponding secrets exist in Cloudflare Workers (via Wrangler):
wrangler secret put DEX_ASSETS_ADMIN_TOKEN_TEST wrangler secret put DEX_ASSETS_ADMIN_TOKEN_PROD wrangler secret put DEX_CATALOG_ADMIN_TOKEN_TEST wrangler secret put DEX_CATALOG_ADMIN_TOKEN_PROD
Preflight Validation Preflight runs comprehensive checks before allowing deployment.
Test Preflight dex release preflight --env test
Checks:
✅ Entry runtime audit : All entries pass validation
✅ Protected asset coverage : All active lookups have mappings
✅ Catalog validation : Manifest integrity and linkage
✅ HTML secure checks : No forbidden patterns or legacy code
Output (success):
preflight:env=test ✓ entry audit (15 entries, inventory=15 rows) ✓ protected asset coverage (15 active lookups) ✓ catalog validation (15 manifest rows) ✓ HTML secure checks passed
Production Preflight NEVER skip preflight in production : Use --preflight-env prod for all production deploys.
dex release preflight --env prod
Preflight Failures
No non-exempt entries audited
Error: preflight failed: no non-exempt entries were audited.
Cause:
No entries with entry.json exist in entries/.Solution:
Ensure you have created entries:ls entries/ dex entry audit --all
Error: preflight failed: entry audit failures (3/15) tim-feeney, jane-doe, old-entry
Solution:
Fix failing entries:dex entry audit --slug tim-feeney # Address reported issues dex doctor # Repair entries as needed
Missing protected asset coverage
Generated HTML secure check failure
Error: preflight failed: generated HTML secure check failure
Cause:
One or more entries have:
Legacy Auth0 blocks
Forbidden runtime script hosts (squarespace, sqspcdn)
Missing auth trio
Solution:
Run doctor and repair:dex doctor # Repair affected entries
Release Publishing The dex release publish command deploys assets and catalog to API endpoints.
Test Release
Run preflight
dex release preflight --env test
Publish release
dex release publish --env test
Execution order:
Preflight validation (unless --no-preflight)
Assets publish
Catalog publish
Local snapshot sync
Output: release:publish (test) ✓ preflight passed ✓ assets published (15 mappings) ✓ catalog published (15 manifest rows) ✓ snapshot synced to data/catalog.snapshot.json
Production Release Production policy : NEVER use --no-preflight for production releases.
Run production preflight
dex release preflight --env prod
Dry run (recommended)
dex release publish --env prod --dry-run
This simulates the publish without making changes.
Publish for real
dex release publish --env prod
Output: release:publish (prod) ✓ preflight passed ✓ assets published (15 mappings) hash=a3f2d1b8 ✓ catalog published (15 manifest rows) hash=b4e5c6f9 ✓ snapshot synced to data/catalog.snapshot.json
Skip Preflight (Emergency Only) High-risk operation : Only use in emergencies with explicit approval.
dex release publish --env test --no-preflight
Custom API Endpoints Override default endpoints:
dex release publish --env test \ --api-base https://custom-api.example.com \ --token my-custom-token
Per-service overrides:
dex release publish --env test \ --assets-api-base https://assets-api.example.com \ --assets-token assets-token \ --catalog-api-base https://catalog-api.example.com \ --catalog-token catalog-token
Site Deployment After publishing the release, deploy the site repo to trigger Cloudflare Pages build.
Deploy to Test Or explicitly:
dex deploy --preflight-env test
This:
Runs preflight validation (test env)
Executes git push to remote
Triggers Cloudflare Pages build
Output:
✓ preflight passed (test) ✓ git push origin main branch: main remote: origin Pages build: https://dash.cloudflare.com/...
Deploy to Production Preferred production command : Always include --preflight-env prod.
dex deploy --preflight-env prod
Skip Preflight (Emergency Only) dex deploy --no-preflight
Emergency-only flag : Bypasses all validation. Use with extreme caution.
Custom Remote dex deploy --remote upstream
Skip Set-Upstream For branches that already track a remote:
dex deploy --no-set-upstream
Canonical Production Workflow The recommended end-to-end workflow:
Validate test environment
dex release preflight --env test
Publish to test
dex release publish --env test
Validate production environment
dex release preflight --env prod
Publish to production
dex release publish --env prod
Deploy site
dex deploy --preflight-env prod
Stop conditions (abort deployment if any occur):
Preflight failure
Missing active lookup coverage
Generated HTML secure check failure
Admin token authentication error
Rollback Strategy If a deployment causes issues:
Revert Catalog Pull the previous version from production:
dex catalog pull --env prod
This overwrites catalog.editorial.json with the remote version.
Revert Site Use git to revert:
git revert HEAD git push origin main
Or roll back to a specific commit:
git reset --hard < previous-commi t > git push --force origin main
Force push to main/master requires special approval. Coordinate with team leads.
Revert Assets Assets are immutable once published. To “revert”:
Edit data/protected.assets.json to previous state
Re-publish:
dex assets publish --env prod
TUI Dashboard Shortcuts For interactive deployment, use the dashboard:
Release Flow Select Release in dashboard:
Preflight: Runs validation
Publish Test: Deploys to test
Publish Prod: Deploys to production (requires typed confirmation)
Deploy Shortcut From dashboard, select Deploy :
Runs preflight (test by default)
Executes git push
Shows push output
Verification Commands Post-deployment health checks:
Manual Contract npm run verify:dex-manual
Verifies README documentation matches actual command surface.
Full Gate npm run phase1:all npm run sanitize:all
Runs comprehensive validation suite.
Troubleshooting
Error: Git push failed. error: failed to push some refs
Solution:
Pull latest changes first:git pull --rebase origin main dex deploy --preflight-env prod
Not inside a git repository
Error: Not inside a git repository.
Solution:
Ensure you’re in the site repo root:cd ~/path/to/dexdsl.github.io dex deploy
Detached HEAD is not deployable
Error: Detached HEAD is not deployable. Check out a branch first.
Solution:
Check out a branch:git checkout main dex deploy
Best Practices
Never Skip Preflight in Prod Always run preflight validation before production deploys
Test Before Prod Deploy to test environment first, verify, then deploy to prod
Use Dry Run Preview changes with --dry-run before real publish
Version Control Snapshots Commit catalog.snapshot.json after successful deploys for audit trail
Next Steps