| name | app-platform-migration |
| version | 1.0.0 |
| min_doctl_version | 1.82.0 |
| description | Migrate applications from Heroku, AWS, Render, Railway, Fly.io, or Docker Compose to DigitalOcean App Platform. Use when converting existing apps, mapping services, refactoring platform-specific code, or creating app specs from other platform configurations. |
| related_skills | ["designer","postgres","managed-db-services","networking","deployment"] |
| deprecated | false |
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, heroku.yml) → See Heroku Deep Chapter 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, heroku.yml | Full (deep chapter) |
| 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
"Migrate this app to App Platform: https://github.com/myorg/myapp"
With Branch Specification
"Migrate my Heroku app. Put test config in 'migrate/test', prod in 'migrate/prod'"
Full workflows: See workflow-examples.md
Heroku Migration (Deep Chapter)
For Heroku-specific migrations, a comprehensive chapter is available with deep knowledge of Procfile, app.json, heroku.yml, buildpacks, pipelines, add-ons, and CLI mapping.
Start here: Read heroku-overview.md to determine the migration mode (Q&A, Guided, or Auto-Migrate), then follow the routing to:
- heroku-concepts.md — Heroku config file schemas, CLI commands, buildpack detection, pipeline structure
- heroku-mapping.md — Component types, build config, env vars, instance sizes, networking, regions
- heroku-addons.md — Add-on detection from app.json, DO managed service equivalents, external alternatives
- heroku-workflows.md — Step-by-step procedures for Q&A, Guided, and Auto-Migrate modes
Quick Mapping (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 |
| Pipelines | GitHub Actions |
| Review Apps | Preview environments |
| Heroku Scheduler | jobs (CRON_TRIGGER) |
Full mapping: See heroku-mapping.md
Quick Mapping Reference
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
Heroku (Deep Chapter)
General
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
Documentation Links
