App Platform Migration Skill
Migrate existing applications to DigitalOcean App Platform with honest capability assessment.
Philosophy
This skill is an honest partner, not a magic wand. It:
- Analyzes thoroughly before proposing changes
- Maps what it can with confidence
- Acknowledges gaps clearly and specifically
- Asks before proceeding when uncertain
- Never guesses or ignores incompatibilities
Tip: For complex multi-step migrations, use the planner skill first. For all available skills, see root SKILL.md.
Quick Decision
What's your source platform?
├── Heroku (Procfile, app.json) → See Quick Start below
├── Docker Compose → See Quick Start below
├── Render/Railway/Fly.io → See Quick Start below
├── AWS ECS/App Runner → Complex migration, see reference
└── Just Dockerfile → See Quick Start below
Supported Platforms
| Platform | Config Files | Support Level |
|---|---|---|
| Heroku | Procfile, app.json | Full |
| Docker Compose | docker-compose.yml | Full |
| Render | render.yaml | Full |
| Railway | railway.json, railway.toml | Full |
| Fly.io | fly.toml | Full |
| AWS ECS | Task Definition JSON | Partial |
| AWS App Runner | apprunner.yaml | Partial |
| Generic Docker | Dockerfile only | Full |
Migration Workflow
Phase 1: DISCOVERY
├── Clone/access repository
├── Detect source platform
├── Analyze architecture
└── Inventory all services
Phase 2: MAPPING
├── Map services → App Platform components
├── Map databases → Managed databases
├── Map storage → Spaces
├── Map secrets → GitHub Secrets
└── Identify unmappable items → REPORT TO USER
Phase 3: REFACTORING
├── Create target branch(es)
├── Update environment variables
├── Remove platform-specific code
├── Update Dockerfile if needed
└── Generate app spec
Phase 4: VALIDATION
├── Validate: doctl apps spec validate
├── Review changes with user
└── Generate migration checklist
Phase 5: HANDOFF
├── Push branches to repo
├── Provide manual steps checklist
└── Suggest deployment skill
Quick Start
Basic Migration
# User provides repo URL
"Migrate this app to App Platform: https://github.com/myorg/myapp"
# AI will:
# 1. Clone and analyze
# 2. Detect platform
# 3. Present mapping proposal
# 4. Ask for approval
# 5. Create branch with refactored code + app spec
With Branch Specification
"Migrate my Heroku app. Put test config in 'migrate/test', prod in 'migrate/prod'"
Full workflows: See workflow-examples.md
Quick Mapping Reference
Heroku
| Heroku | App Platform |
|---|---|
web process | services |
worker process | workers |
release phase | jobs (PRE_DEPLOY) |
heroku-postgresql | Managed Postgres |
heroku-redis | Managed Valkey |
| Config Vars | GitHub Secrets |
Docker Compose
| Docker Compose | App Platform |
|---|---|
services.<name>.ports | services |
services.<name> (no ports) | workers |
services.postgres | Managed Postgres |
services.redis | Managed Valkey |
volumes | Spaces (no persistent volumes) |
Full mapping tables: See platform-mappings.md
Unmappable Items (Quick Reference)
| Source | Issue | Options |
|---|---|---|
| CloudFront CDN | No DO CDN | External CDN (Cloudflare) or skip |
| AWS Secrets Manager | Different model | GitHub Secrets |
| Persistent volumes | Not supported | Spaces for files, managed DB for data |
| ARM containers | AMD64 only | Rebuild for AMD64 |
Full list: See platform-mappings.md
Output Artifacts
| File | Purpose |
|---|---|
.do/app.yaml | App Platform specification |
.do/deploy.template.yaml | Deploy to DO button |
MIGRATION.md | Migration checklist and status |
.env.example | Environment variable template |
App spec templates: See app-spec-generation.md
Scripts
| Script | Purpose |
|---|---|
scripts/detect_platform.py | Detect source platform from files |
scripts/analyze_architecture.py | Analyze application architecture |
scripts/generate_app_spec.py | Generate .do/app.yaml |
scripts/generate_checklist.py | Generate migration checklist |
Reference Files
- platform-mappings.md - Full platform detection, all mapping tables, gotchas
- code-refactoring.md - Env var updates, S3/Valkey migration, data migration
- workflow-examples.md - Heroku, Docker Compose, AWS ECS walkthroughs
- app-spec-generation.md - Test/prod spec templates, defaults
Common Issues (Quick Fixes)
| Issue | Cause | Fix |
|---|---|---|
| App spec validation fails | Invalid YAML | Check indentation, doctl apps spec validate |
| Database connection fails | Wrong URL format | Use ${db.DATABASE_URL} binding |
| Build fails | Missing dependencies | Check Dockerfile build deps |
| Port binding fails | Wrong PORT handling | Bind to $PORT or 0.0.0.0:8080 |
| Health check fails | Wrong path | Verify /health endpoint exists |
Full troubleshooting: See code-refactoring.md
Integration with Other Skills
- → deployment: GitHub Actions workflow after migration
- → postgres: Complex database setup, schema isolation
- → devcontainers: Local dev environment post-migration
- → troubleshooting: Debug container for migration issues