From a7f713a9f57268b7a4ccc7c2a9ea6f870106a518 Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 27 Aug 2025 10:31:30 -0700 Subject: [PATCH 1/6] heroku migration doc --- docs/tutorials/migrating-from-heroku.md | 176 ++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/tutorials/migrating-from-heroku.md diff --git a/docs/tutorials/migrating-from-heroku.md b/docs/tutorials/migrating-from-heroku.md new file mode 100644 index 000000000..8541a2b9a --- /dev/null +++ b/docs/tutorials/migrating-from-heroku.md @@ -0,0 +1,176 @@ +--- +sidebar_position: 100 +description: Deploy your Heroku Applications in your own Cloud Account with Defang +--- + +# Migrating from Heroku + +This tutorial will guide you through the process of migrating your Heroku applications to your own cloud account with Defang. This will allow you to reduce cost, gain more control, and access to the complete range of available cloud services. + +## Pre-requisites +* [A Defang Account](/docs/concepts/authentication) +* [The Defang CLI](/docs/getting-started#install-the-defang-cli) +* [The Heroku CLI (optional, but recommended)](https://devcenter.heroku.com/articles/heroku-cli#install-the-heroku-cli) +* Cloud Account Credentials + * [AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html) + * [GCP](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment) + +:::tip +**Do I need a Dockerfile?** + +No, Defang will use [Railpack](https://railpack.com/) to automatically build an OCI container for your application based on the source code and dependencies. + +**Do I need a Docker Compose file?** + +No, Defang can automatically generate a compose file for your application. +::: + +## Step 1 - Generating a Docker Compose file + +Navigate to your project's working directory: + +``` +$ cd ~/w/vast-badlands +$ ls +Gemfile Procfile Rakefile bin config.ru lib public test vendor +Gemfile.lock README.md app config db log storage tmp +``` + +Then run `defang init` and select `Migrate from heroku`: +``` +$ defang init +? How would you like to start? [Use arrows to move, type to filter] + Generate with AI + Clone a sample +> Migrate from Heroku +``` + +A web browser may open, prompting you to login to Defang. Then, if you have the `heroku` CLI installed, you may be prompted to login with Heroku. Defang will delegate to the `heroku` CLI to create an authentication token so that it can access information about your deployment. The token `defang` creates will only be valid for 5 minutes. + +:::tip +**What if I don't have the Heroku CLI installed?** +`defang` will prompt you for an auth token. You can paste it into the prompt after [creating one in the Heroku Dashboard](https://dashboard.heroku.com/account/applications/authorizations/new). +::: + +At this point, `defang` will fetch a list of your Heroku applications and prompt you to select the one you would like to migrate. + +``` +$ defang init +? How would you like to start? Migrate from Heroku + * Ok, let's create a compose file for your existing deployment. + * The Heroku CLI is installed, we'll use it to generate a short-lived authorization token +? Select the Heroku application to use as a source: [Use arrows to move, type to filter] +> vast-badlands-staging + vast-badlands-production +``` + +Then, `defang` will request some information about your application from the Heroku API. This information will be used to generate a `compose.yaml` file which can then be deployed with Defang. + +``` +defang init +? How would you like to start? Migrate from heroku + * Ok, let's create a compose file for your existing deployment. + * The Heroku CLI is installed, we'll use it to generate a short-lived authorization token +? Select the Heroku application to use as a source: vast-badlands-production + * Collecting information about "vast-badlands-production"... + * Generating compose file... + * Compose file written to compose.yaml + +Check the files in your favorite editor. +To deploy this project, run + + defang compose up +``` + +At this point, `defang` will have generated a `compose.yaml` file that describes your application and its services. You can review this file in your favorite text editor. + +The application I used had a single `web` dyno: +``` +$ heroku ps -a vast-badlands-production + +=== web (Eco): bin/rails server -p ${PORT:-5000} -e $RAILS_ENV (1) +``` + +And a single postgres database: +``` +heroku addons -a vast-badlands-production + + Add-on Plan Price Max price State + ────────────────────────────────────────── ─────────── ──────────── ───────── ─────── + heroku-postgresql (postgresql-rosy-12345) essential-0 ~$0.007/hour $5/month created + └─ as DATABASE +``` + +The `compose.yaml` file that `defang` generated looks like this: + +```yaml +services: + postgres: + image: postgres:17.4 + environment: + POSTGRES_DB: eb631mzx93pn27 + POSTGRES_USER: postgres + POSTGRES_PASSWORD: + healthcheck: + test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"] + x-defang-postgres: "true" + + web: + build: + context: . + command: + - bin/rails server -p $PORT -e $RAILS_ENV + ports: + - "5000:5000" + environment: + DATABASE_URL: postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@postgres:5432/$POSTGRES_DB + LANG: en_US.UTF-8 + RACK_ENV: production + RAILS_ENV: production + RAILS_LOG_TO_STDOUT: enabled + RAILS_SERVE_STATIC_FILES: enabled + SECRET_KEY_BASE: + PORT: 5000 + POSTGRES_PASSWORD: $POSTGRES_PASSWORD + depends_on: + postgres: + condition: service_healthy + deploy: + resources: + limits: + cpus: '1' + memory: 512M + + release: + build: + context: . + command: + - bin/rails db:migrate + environment: + DATABASE_URL: postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@postgres:5432/$POSTGRES_DB + RAILS_ENV: production + SECRET_KEY_BASE: + depends_on: + postgres: + condition: service_healthy + deploy: + resources: + limits: + cpus: '1' + memory: 512M + restart: "no" +``` + +## Step 2 - Deploying to your cloud account + +Now all you need to do is deploy your application to the cloud. + +* [Deploying to AWS](/docs/tutorials/deploy-to-aws.mdx) +* [Deploying to GCP](/docs/tutorials/deploy-to-gcp.mdx) +* [Deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean.mdx) + +## Step 3 - Migrating your data + +:::tip +If you need help with your migration, please reach out to our support team on Discord. +::: From 45b4df2cb03ee125ddef9e2fe756a862ddba7045 Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 27 Aug 2025 10:50:00 -0700 Subject: [PATCH 2/6] Link to discord --- docs/tutorials/migrating-from-heroku.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/migrating-from-heroku.md b/docs/tutorials/migrating-from-heroku.md index 8541a2b9a..5be86d996 100644 --- a/docs/tutorials/migrating-from-heroku.md +++ b/docs/tutorials/migrating-from-heroku.md @@ -172,5 +172,5 @@ Now all you need to do is deploy your application to the cloud. ## Step 3 - Migrating your data :::tip -If you need help with your migration, please reach out to our support team on Discord. +If you need help with your migration, please reach out to our support team on [Discord](https://s.defang.io/discord). ::: From f0317f26b89a4442bee3a5e0ab31ee70fa85dd13 Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 27 Aug 2025 14:19:02 -0700 Subject: [PATCH 3/6] Apply suggestions from code review --- docs/tutorials/migrating-from-heroku.md | 38 +++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/migrating-from-heroku.md b/docs/tutorials/migrating-from-heroku.md index 5be86d996..e0b41a573 100644 --- a/docs/tutorials/migrating-from-heroku.md +++ b/docs/tutorials/migrating-from-heroku.md @@ -22,7 +22,7 @@ No, Defang will use [Railpack](https://railpack.com/) to automatically build an **Do I need a Docker Compose file?** -No, Defang can automatically generate a compose file for your application. +Defang does require a Docker Compose file to deploy your application, but you don't need to write one from scratch. Defang will automatically generate one for your Heroku application. ::: ## Step 1 - Generating a Docker Compose file @@ -91,7 +91,7 @@ $ heroku ps -a vast-badlands-production === web (Eco): bin/rails server -p ${PORT:-5000} -e $RAILS_ENV (1) ``` -And a single postgres database: +And a single PostgreSQL database: ``` heroku addons -a vast-badlands-production @@ -163,7 +163,39 @@ services: ## Step 2 - Deploying to your cloud account -Now all you need to do is deploy your application to the cloud. +Now all you need to do is deploy your application to the cloud. + +### Deploying to AWS + +If you're deploying to AWS, you'll need to invoke `defang compose up` with your AWS access credentials in the environment: + +``` +AWS_REGION=us-west-2 AWS_PROFILE=default defang compose up --provider aws +``` + +See our full tutorial on [deploying to AWS](/docs/tutorials/deploy-to-aws.mdx). + +### Deploying to GCP + +If you're deploying to GCP, you'll need to invoke `defang compose up` with your GCP project id in the environment: + +``` +GCP_PROJECT_ID=my-project-123 defang compose up --provider gcp +``` + +See our full tutorial on [deploying to GCP](/docs/tutorials/deploy-to-gcp.mdx). + + +### Deploying to DigitalOcean + +If you're deploying to DigitalOcean, you'll need to invoke `defang compose up` with your DigitalOcean project id in the environment: + +``` +DIGITALOCEAN_TOKEN=my-token-123 SPACES_ACCESS_KEY_ID=my-access-key-id SPACES_SECRET_ACCESS_KEY=my-access-key-secret defang compose up --provider digitalocean +``` + +See our full tutorial on [deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean.mdx). + * [Deploying to AWS](/docs/tutorials/deploy-to-aws.mdx) * [Deploying to GCP](/docs/tutorials/deploy-to-gcp.mdx) From 0213924cf18aa0440b2e77bd93f36e682371ba9c Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 27 Aug 2025 14:19:38 -0700 Subject: [PATCH 4/6] removing redundant links --- docs/tutorials/migrating-from-heroku.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/tutorials/migrating-from-heroku.md b/docs/tutorials/migrating-from-heroku.md index e0b41a573..4de63b172 100644 --- a/docs/tutorials/migrating-from-heroku.md +++ b/docs/tutorials/migrating-from-heroku.md @@ -196,11 +196,6 @@ DIGITALOCEAN_TOKEN=my-token-123 SPACES_ACCESS_KEY_ID=my-access-key-id SPACES_SEC See our full tutorial on [deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean.mdx). - -* [Deploying to AWS](/docs/tutorials/deploy-to-aws.mdx) -* [Deploying to GCP](/docs/tutorials/deploy-to-gcp.mdx) -* [Deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean.mdx) - ## Step 3 - Migrating your data :::tip From 47c6c39bca81500292d90d19fc92708401865c35 Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 27 Aug 2025 14:20:28 -0700 Subject: [PATCH 5/6] remove file extension from links --- docs/tutorials/migrating-from-heroku.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/migrating-from-heroku.md b/docs/tutorials/migrating-from-heroku.md index 4de63b172..8e46a2ce9 100644 --- a/docs/tutorials/migrating-from-heroku.md +++ b/docs/tutorials/migrating-from-heroku.md @@ -173,7 +173,7 @@ If you're deploying to AWS, you'll need to invoke `defang compose up` with your AWS_REGION=us-west-2 AWS_PROFILE=default defang compose up --provider aws ``` -See our full tutorial on [deploying to AWS](/docs/tutorials/deploy-to-aws.mdx). +See our full tutorial on [deploying to AWS](/docs/tutorials/deploy-to-aws). ### Deploying to GCP @@ -183,7 +183,7 @@ If you're deploying to GCP, you'll need to invoke `defang compose up` with your GCP_PROJECT_ID=my-project-123 defang compose up --provider gcp ``` -See our full tutorial on [deploying to GCP](/docs/tutorials/deploy-to-gcp.mdx). +See our full tutorial on [deploying to GCP](/docs/tutorials/deploy-to-gcp). ### Deploying to DigitalOcean @@ -194,7 +194,7 @@ If you're deploying to DigitalOcean, you'll need to invoke `defang compose up` w DIGITALOCEAN_TOKEN=my-token-123 SPACES_ACCESS_KEY_ID=my-access-key-id SPACES_SECRET_ACCESS_KEY=my-access-key-secret defang compose up --provider digitalocean ``` -See our full tutorial on [deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean.mdx). +See our full tutorial on [deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean). ## Step 3 - Migrating your data From a69a6a9d6c3814eb42dbd26ff1ecd90c4ca08959 Mon Sep 17 00:00:00 2001 From: Jordan Stephens Date: Wed, 27 Aug 2025 15:26:32 -0700 Subject: [PATCH 6/6] Apply suggestions from code review --- docs/tutorials/migrating-from-heroku.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/docs/tutorials/migrating-from-heroku.md b/docs/tutorials/migrating-from-heroku.md index 8e46a2ce9..4480078bc 100644 --- a/docs/tutorials/migrating-from-heroku.md +++ b/docs/tutorials/migrating-from-heroku.md @@ -177,24 +177,7 @@ See our full tutorial on [deploying to AWS](/docs/tutorials/deploy-to-aws). ### Deploying to GCP -If you're deploying to GCP, you'll need to invoke `defang compose up` with your GCP project id in the environment: - -``` -GCP_PROJECT_ID=my-project-123 defang compose up --provider gcp -``` - -See our full tutorial on [deploying to GCP](/docs/tutorials/deploy-to-gcp). - - -### Deploying to DigitalOcean - -If you're deploying to DigitalOcean, you'll need to invoke `defang compose up` with your DigitalOcean project id in the environment: - -``` -DIGITALOCEAN_TOKEN=my-token-123 SPACES_ACCESS_KEY_ID=my-access-key-id SPACES_SECRET_ACCESS_KEY=my-access-key-secret defang compose up --provider digitalocean -``` - -See our full tutorial on [deploying to DigitalOcean](/docs/tutorials/deploy-to-digitalocean). +GCP support for deployments without Dockerfiles coming soon. ## Step 3 - Migrating your data