home / skills / digitalocean-labs / do-app-platform-skills / migration

migration skill

safe

This skill helps you migrate apps to DigitalOcean App Platform by mapping services, refactoring code, and generating compliant app specs.

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

Review the files below or copy the command above to add this skill to your agents.

Files (17)

SKILL.md

8.4 KB

---
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/)

Overview

This skill migrates applications from Heroku, AWS, Render, Railway, Fly.io, or Docker Compose into DigitalOcean App Platform. It provides an honest capability assessment, maps services and resources to App Platform equivalents, and generates app specs and a migration checklist. Use it to automate mapping, refactor platform-specific code, and produce branch-ready artifacts for validation and deployment.

How this skill works

The skill inspects repository files (Procfile, app.json, heroku.yml, docker-compose.yml, fly.toml, Dockerfile, ECS task JSON, etc.) and detects the source platform and architecture. It inventories services, databases, volumes, ports, and secrets, then generates a mapping proposal and an app spec (.do/app.yaml) while flagging unmappable items and risks. After user approval it can create branches with refactored code, environment templates, and a MIGRATION.md checklist.

When to use it

Converting a Heroku app (Procfile, app.json, or heroku.yml) to App Platform
Moving multi-service projects defined with docker-compose to App Platform
Migrating apps hosted on Render, Railway, or Fly.io to DigitalOcean
Creating App Platform specs from a Dockerfile or ECS/App Runner configs
Preparing code and branches for a production migration with validation steps

Best practices

Run the discovery step on a cloned repo and provide branch targets before making changes
Start with a test or staging app spec and validate using doctl apps spec validate
Address unmappable features explicitly and choose external alternatives where needed
Keep secrets in GitHub Secrets and map database bindings to managed databases
Use the planner skill for complex, multi-step migrations to sequence tasks

Example use cases

Auto-generate .do/app.yaml and a migration branch for a Heroku web+worker app
Translate docker-compose services into App Platform services and workers
Detect managed resources (Postgres, Redis) and propose DigitalOcean managed equivalents
Create a deployable branch that replaces platform-specific CLI hooks with App Platform jobs
Produce a migration checklist and troubleshooting notes for failed builds or health checks

FAQ

Will the skill migrate platform-specific add-ons automatically?

The skill maps common add-ons (Postgres, Redis) to managed equivalents and suggests external alternatives for unsupported items; it will not silently replace proprietary add-ons without explicit user approval.

Can it handle persistent volumes from other platforms?

DigitalOcean App Platform does not support persistent container volumes; the skill recommends Spaces or managed databases and documents the required code and architecture changes.