app-platform-migration

by @digitalocean-labs in DevOps & Cloud

# Install this skill:

npx skills add digitalocean-labs/do-app-platform-skills --skill "app-platform-migration"

Install specific skill from multi-skill repository

# 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.

# SKILL.md

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) → See Quick Start 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`	Full
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

Quick Mapping Reference

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

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

platform-mappings.md - Full platform detection, all mapping tables, gotchas
code-refactoring.md - Env var updates, S3/Valkey migration, data migration
workflow-examples.md - Heroku, 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

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.