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.

---

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

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