Deployment Checklist

Checklist for deploying a new release of Docling Studio. Applies to both self-hosted and Hugging Face Space deployments.

Pre-Deploy

• [ ] Release branch merged to main via PR
• [ ] Git tag vX.Y.Z created on main
• [ ] Release audit passed (score >= 80, 0 CRITICAL) — see docs/audit/master.md
• [ ] CHANGELOG.md section finalized with release date
• [ ] frontend/package.json version matches the tag
• [ ] All CI checks green on the tagged commit
• [ ] Docker images built and pushed to ghcr.io:
• X.Y.Z-remote, X.Y.Z-local
• X.Y-remote, X.Y-local
• latest-remote, latest-local

Deploy — Self-Hosted (Docker Compose)

• [ ] Pull the new image:

  docker compose pull
  

• [ ] Check environment variables (.env or docker-compose.override.yml):
• CONVERSION_ENGINE (local / remote)
• RATE_LIMIT_RPM
• MAX_FILE_SIZE_MB
• MAX_CONCURRENT_ANALYSES
• [ ] Start the stack:

  docker compose up -d --wait
  

• [ ] Verify health endpoint:

  curl -s http://localhost:3000/api/health | jq .
  # Expected: {"status":"ok","engine":"...","version":"X.Y.Z","deploymentMode":"self-hosted"}
  

Deploy — Hugging Face Space

• [ ] Upload to HF Space via huggingface-cli:

  huggingface-cli upload <space-id> . . --repo-type space
  

• [ ] Set environment variables in HF Space settings
• [ ] Wait for build to complete in HF Space logs
• [ ] Verify the app loads and health endpoint returns correct version

Post-Deploy Smoke Test

• [ ] Home page loads
• [ ] Upload a PDF — document appears in the list
• [ ] Run an analysis — completes without error
• [ ] View results — markdown, HTML, bbox overlays render correctly
• [ ] Download results
• [ ] If local mode: test chunking
• [ ] Check /api/health returns the new version

Rollback Triggers

Rollback immediately if any of these occur:

Trigger	Action
Health endpoint returns error or wrong version	Rollback
Upload or analysis fails on a previously working PDF	Rollback
Frontend shows blank page or JS errors	Rollback
Error rate > 5% in the first 15 minutes	Rollback

For rollback procedure, see rollback-playbook.md.