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
# 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
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)
- heroku-overview.md - Entry point: read first for any Heroku migration
- heroku-concepts.md - Procfile, app.json, heroku.yml, pipelines, CLI
- heroku-mapping.md - Deep Heroku → App Platform feature mapping
- heroku-addons.md - Add-on ecosystem mapping (Postgres, Redis, etc.)
- heroku-workflows.md - Migration workflows: Q&A, Guided, Auto-Migrate
General
- platform-mappings.md - All platform detection, mapping tables, gotchas
- code-refactoring.md - Env var updates, S3/Valkey migration, data migration
- workflow-examples.md - 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
Documentation Links
1---2name: app-platform-migration3description: 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.4---56# App Platform Migration Skill78Migrate existing applications to DigitalOcean App Platform with honest capability assessment.910## Philosophy1112This skill is an honest partner, not a magic wand. It:13141. **Analyzes thoroughly** before proposing changes152. **Maps what it can** with confidence163. **Acknowledges gaps** clearly and specifically174. **Asks before proceeding** when uncertain185. **Never guesses** or ignores incompatibilities1920> **Tip**: For complex multi-step migrations, use the **planner** skill first. For all available skills, see [root SKILL.md](../../SKILL.md).2122---2324## Quick Decision2526```27What's your source platform?28├── Heroku (Procfile, app.json, heroku.yml) → See Heroku Deep Chapter below29├── Docker Compose → See Quick Start below30├── Render/Railway/Fly.io → See Quick Start below31├── AWS ECS/App Runner → Complex migration, see reference32└── Just Dockerfile → See Quick Start below33```3435---3637## Supported Platforms3839| Platform | Config Files | Support Level |40|----------|--------------|---------------|41| **Heroku** | `Procfile`, `app.json`, `heroku.yml` | Full (deep chapter) |42| **Docker Compose** | `docker-compose.yml` | Full |43| **Render** | `render.yaml` | Full |44| **Railway** | `railway.json`, `railway.toml` | Full |45| **Fly.io** | `fly.toml` | Full |46| **AWS ECS** | Task Definition JSON | Partial |47| **AWS App Runner** | `apprunner.yaml` | Partial |48| **Generic Docker** | `Dockerfile` only | Full |4950---5152## Migration Workflow5354```55Phase 1: DISCOVERY56├── Clone/access repository57├── Detect source platform58├── Analyze architecture59└── Inventory all services6061Phase 2: MAPPING62├── Map services → App Platform components63├── Map databases → Managed databases64├── Map storage → Spaces65├── Map secrets → GitHub Secrets66└── Identify unmappable items → REPORT TO USER6768Phase 3: REFACTORING69├── Create target branch(es)70├── Update environment variables71├── Remove platform-specific code72├── Update Dockerfile if needed73└── Generate app spec7475Phase 4: VALIDATION76├── Validate: doctl apps spec validate77├── Review changes with user78└── Generate migration checklist7980Phase 5: HANDOFF81├── Push branches to repo82├── Provide manual steps checklist83└── Suggest deployment skill84```8586---8788## Quick Start8990### Basic Migration9192```bash93# User provides repo URL94"Migrate this app to App Platform: https://github.com/myorg/myapp"9596# AI will:97# 1. Clone and analyze98# 2. Detect platform99# 3. Present mapping proposal100# 4. Ask for approval101# 5. Create branch with refactored code + app spec102```103104### With Branch Specification105106```bash107"Migrate my Heroku app. Put test config in 'migrate/test', prod in 'migrate/prod'"108```109110**Full workflows**: See [workflow-examples.md](reference/workflow-examples.md)111112---113114## Heroku Migration (Deep Chapter)115116For Heroku-specific migrations, a comprehensive chapter is available with deep knowledge of Procfile, app.json, heroku.yml, buildpacks, pipelines, add-ons, and CLI mapping.117118**Start here**: Read **[heroku-overview.md](reference/heroku/heroku-overview.md)** to determine the migration mode (Q&A, Guided, or Auto-Migrate), then follow the routing to:119120- **[heroku-concepts.md](reference/heroku/heroku-concepts.md)** — Heroku config file schemas, CLI commands, buildpack detection, pipeline structure121- **[heroku-mapping.md](reference/heroku/heroku-mapping.md)** — Component types, build config, env vars, instance sizes, networking, regions122- **[heroku-addons.md](reference/heroku/heroku-addons.md)** — Add-on detection from app.json, DO managed service equivalents, external alternatives123- **[heroku-workflows.md](reference/heroku/heroku-workflows.md)** — Step-by-step procedures for Q&A, Guided, and Auto-Migrate modes124125### Quick Mapping (Heroku)126127| Heroku | App Platform |128|--------|--------------|129| `web` process | `services` |130| `worker` process | `workers` |131| `release` phase | `jobs` (PRE_DEPLOY) |132| `heroku-postgresql` | Managed Postgres |133| `heroku-redis` | Managed Valkey |134| Config Vars | GitHub Secrets |135| Pipelines | GitHub Actions |136| Review Apps | Preview environments |137| Heroku Scheduler | `jobs` (CRON_TRIGGER) |138139**Full mapping**: See [heroku-mapping.md](reference/heroku/heroku-mapping.md)140141---142143## Quick Mapping Reference144145### Docker Compose146147| Docker Compose | App Platform |148|----------------|--------------|149| `services.<name>.ports` | `services` |150| `services.<name>` (no ports) | `workers` |151| `services.postgres` | Managed Postgres |152| `services.redis` | Managed Valkey |153| `volumes` | Spaces (no persistent volumes) |154155**Full mapping tables**: See [platform-mappings.md](reference/platform-mappings.md)156157---158159## Unmappable Items (Quick Reference)160161| Source | Issue | Options |162|--------|-------|---------|163| CloudFront CDN | No DO CDN | External CDN (Cloudflare) or skip |164| AWS Secrets Manager | Different model | GitHub Secrets |165| Persistent volumes | Not supported | Spaces for files, managed DB for data |166| ARM containers | AMD64 only | Rebuild for AMD64 |167168**Full list**: See [platform-mappings.md](reference/platform-mappings.md#unmappable-items)169170---171172## Output Artifacts173174| File | Purpose |175|------|---------|176| `.do/app.yaml` | App Platform specification |177| `.do/deploy.template.yaml` | Deploy to DO button |178| `MIGRATION.md` | Migration checklist and status |179| `.env.example` | Environment variable template |180181**App spec templates**: See [app-spec-generation.md](reference/app-spec-generation.md)182183---184185## Scripts186187| Script | Purpose |188|--------|---------|189| `scripts/detect_platform.py` | Detect source platform from files |190| `scripts/analyze_architecture.py` | Analyze application architecture |191| `scripts/generate_app_spec.py` | Generate .do/app.yaml |192| `scripts/generate_checklist.py` | Generate migration checklist |193194---195196## Reference Files197198### Heroku (Deep Chapter)199200- **[heroku-overview.md](reference/heroku/heroku-overview.md)** - Entry point: read first for any Heroku migration201- **[heroku-concepts.md](reference/heroku/heroku-concepts.md)** - Procfile, app.json, heroku.yml, pipelines, CLI202- **[heroku-mapping.md](reference/heroku/heroku-mapping.md)** - Deep Heroku → App Platform feature mapping203- **[heroku-addons.md](reference/heroku/heroku-addons.md)** - Add-on ecosystem mapping (Postgres, Redis, etc.)204- **[heroku-workflows.md](reference/heroku/heroku-workflows.md)** - Migration workflows: Q&A, Guided, Auto-Migrate205206### General207208- **[platform-mappings.md](reference/platform-mappings.md)** - All platform detection, mapping tables, gotchas209- **[code-refactoring.md](reference/code-refactoring.md)** - Env var updates, S3/Valkey migration, data migration210- **[workflow-examples.md](reference/workflow-examples.md)** - Docker Compose, AWS ECS walkthroughs211- **[app-spec-generation.md](reference/app-spec-generation.md)** - Test/prod spec templates, defaults212213---214215## Common Issues (Quick Fixes)216217| Issue | Cause | Fix |218|-------|-------|-----|219| App spec validation fails | Invalid YAML | Check indentation, `doctl apps spec validate` |220| Database connection fails | Wrong URL format | Use `${db.DATABASE_URL}` binding |221| Build fails | Missing dependencies | Check Dockerfile build deps |222| Port binding fails | Wrong PORT handling | Bind to `$PORT` or `0.0.0.0:8080` |223| Health check fails | Wrong path | Verify `/health` endpoint exists |224225**Full troubleshooting**: See [code-refactoring.md](reference/code-refactoring.md#troubleshooting-code-changes)226227---228229## Integration with Other Skills230231- **→ deployment**: GitHub Actions workflow after migration232- **→ postgres**: Complex database setup, schema isolation233- **→ devcontainers**: Local dev environment post-migration234- **→ troubleshooting**: Debug container for migration issues235236---237238## Documentation Links239240- [App Spec Reference](https://docs.digitalocean.com/products/app-platform/reference/app-spec/)241- [Heroku Migration Guide](https://docs.digitalocean.com/products/app-platform/how-to/migrate-from-heroku/)242- [Deploy to DO Button](https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/)
digitalocean-labs