App Platform Migration

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:

1. Analyzes thoroughly before proposing changes
2. Maps what it can with confidence
3. Acknowledges gaps clearly and specifically
4. Asks before proceeding when uncertain
5. Never guesses or ignores incompatibilities

> Tip: For complex multi-step migrations, use the planner skill first. For all available skills, see [root SKILL.md](../../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](reference/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](reference/heroku/heroku-overview.md) to determine the migration mode (Q&A, Guided, or Auto-Migrate), then follow the routing to:

• [heroku-concepts.md](reference/heroku/heroku-concepts.md) — Heroku config file schemas, CLI commands, buildpack detection, pipeline structure
• [heroku-mapping.md](reference/heroku/heroku-mapping.md) — Component types, build config, env vars, instance sizes, networking, regions
• [heroku-addons.md](reference/heroku/heroku-addons.md) — Add-on detection from app.json, DO managed service equivalents, external alternatives
• [heroku-workflows.md](reference/heroku/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 (PREDEPLOY) | | heroku-postgresql | Managed Postgres | | heroku-redis | Managed Valkey | | Config Vars | GitHub Secrets | | Pipelines | GitHub Actions | | Review Apps | Preview environments | | Heroku Scheduler | jobs (CRONTRIGGER) |

Full mapping: See [heroku-mapping.md](reference/heroku/heroku-mapping.md)

---

Quick Mapping Reference

Docker Compose

| Docker Compose | App Platform | |----------------|--------------| | services..ports | services | | services. (no ports) | workers | | services.postgres | Managed Postgres | | services.redis | Managed Valkey | | volumes | Spaces (no persistent volumes) |

Full mapping tables: See [platform-mappings.md](reference/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](reference/platform-mappings.md#unmappable-items)

---

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](reference/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](reference/heroku/heroku-overview.md) - Entry point: read first for any Heroku migration
• [heroku-concepts.md](reference/heroku/heroku-concepts.md) - Procfile, app.json, heroku.yml, pipelines, CLI
• [heroku-mapping.md](reference/heroku/heroku-mapping.md) - Deep Heroku → App Platform feature mapping
• [heroku-addons.md](reference/heroku/heroku-addons.md) - Add-on ecosystem mapping (Postgres, Redis, etc.)
• [heroku-workflows.md](reference/heroku/heroku-workflows.md) - Migration workflows: Q&A, Guided, Auto-Migrate

General

• [platform-mappings.md](reference/platform-mappings.md) - All platform detection, mapping tables, gotchas
• [code-refactoring.md](reference/code-refactoring.md) - Env var updates, S3/Valkey migration, data migration
• [workflow-examples.md](reference/workflow-examples.md) - Docker Compose, AWS ECS walkthroughs
• [app-spec-generation.md](reference/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](reference/code-refactoring.md#troubleshooting-code-changes)

---

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

• App Spec Reference
• Heroku Migration Guide
• Deploy to DO Button

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: digitalocean-labs
• Source: digitalocean-labs/do-app-platform-skills
• License: MIT

Install and usage instructions live in the source repository linked above.