app-platform-migration

---
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:

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

```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](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` (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](reference/heroku/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](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](https://docs.digitalocean.com/products/app-platform/reference/app-spec/)
- [Heroku Migration Guide](https://docs.digitalocean.com/products/app-platform/how-to/migrate-from-heroku/)
- [Deploy to DO Button](https://docs.digitalocean.com/products/app-platform/how-to/add-deploy-do-button/)

More agent context in digitalocean-labs/do-app-platform-skills

13 other files this repository gives its agents.