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

code

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

code

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

bash

# 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

bash

"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

app-platform-migration