Skip to content

Commit 87cf7e3

Browse files
jordanstephensjordanstephens
committed
heroku migration docs (#276)
* heroku migration doc * Link to discord * Apply suggestions from code review * removing redundant links * remove file extension from links * Apply suggestions from code review
1 parent 29529be commit 87cf7e3

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎docs/tutorials/migrating-from-heroku.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
sidebar_position: 100
3+
description: Deploy your Heroku Applications in your own Cloud Account with Defang
4+
---
5+
6+
# Migrating from Heroku
7+
8+
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.
9+
10+
## Pre-requisites
11+
* [A Defang Account](/docs/concepts/authentication)
12+
* [The Defang CLI](/docs/getting-started#install-the-defang-cli)
13+
* [The Heroku CLI (optional, but recommended)](https://devcenter.heroku.com/articles/heroku-cli#install-the-heroku-cli)
14+
* Cloud Account Credentials
15+
* [AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html)
16+
* [GCP](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment)
17+
18+
:::tip
19+
**Do I need a Dockerfile?**
20+
21+
No, Defang will use [Railpack](https://railpack.com/) to automatically build an OCI container for your application based on the source code and dependencies.
22+
23+
**Do I need a Docker Compose file?**
24+
25+
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.
26+
:::
27+
28+
## Step 1 - Generating a Docker Compose file
29+
30+
Navigate to your project's working directory:
31+
32+
```
33+
$ cd ~/w/vast-badlands
34+
$ ls
35+
Gemfile Procfile Rakefile bin config.ru lib public test vendor
36+
Gemfile.lock README.md app config db log storage tmp
37+
```
38+
39+
Then run `defang init` and select `Migrate from heroku`:
40+
```
41+
$ defang init
42+
? How would you like to start? [Use arrows to move, type to filter]
43+
Generate with AI
44+
Clone a sample
45+
> Migrate from Heroku
46+
```
47+
48+
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.
49+
50+
:::tip
51+
**What if I don't have the Heroku CLI installed?**
52+
`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).
53+
:::
54+
55+
At this point, `defang` will fetch a list of your Heroku applications and prompt you to select the one you would like to migrate.
56+
57+
```
58+
$ defang init
59+
? How would you like to start? Migrate from Heroku
60+
* Ok, let's create a compose file for your existing deployment.
61+
* The Heroku CLI is installed, we'll use it to generate a short-lived authorization token
62+
? Select the Heroku application to use as a source: [Use arrows to move, type to filter]
63+
> vast-badlands-staging
64+
vast-badlands-production
65+
```
66+
67+
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.
68+
69+
```
70+
defang init
71+
? How would you like to start? Migrate from heroku
72+
* Ok, let's create a compose file for your existing deployment.
73+
* The Heroku CLI is installed, we'll use it to generate a short-lived authorization token
74+
? Select the Heroku application to use as a source: vast-badlands-production
75+
* Collecting information about "vast-badlands-production"...
76+
* Generating compose file...
77+
* Compose file written to compose.yaml
78+
79+
Check the files in your favorite editor.
80+
To deploy this project, run
81+
82+
defang compose up
83+
```
84+
85+
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.
86+
87+
The application I used had a single `web` dyno:
88+
```
89+
$ heroku ps -a vast-badlands-production
90+
91+
=== web (Eco): bin/rails server -p ${PORT:-5000} -e $RAILS_ENV (1)
92+
```
93+
94+
And a single PostgreSQL database:
95+
```
96+
heroku addons -a vast-badlands-production
97+
98+
Add-on Plan Price Max price State
99+
────────────────────────────────────────── ─────────── ──────────── ───────── ───────
100+
heroku-postgresql (postgresql-rosy-12345) essential-0 ~$0.007/hour $5/month created
101+
└─ as DATABASE
102+
```
103+
104+
The `compose.yaml` file that `defang` generated looks like this:
105+
106+
```yaml
107+
services:
108+
postgres:
109+
image: postgres:17.4
110+
environment:
111+
POSTGRES_DB: eb631mzx93pn27
112+
POSTGRES_USER: postgres
113+
POSTGRES_PASSWORD:
114+
healthcheck:
115+
test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"]
116+
x-defang-postgres: "true"
117+
118+
web:
119+
build:
120+
context: .
121+
command:
122+
- bin/rails server -p $PORT -e $RAILS_ENV
123+
ports:
124+
- "5000:5000"
125+
environment:
126+
DATABASE_URL: postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@postgres:5432/$POSTGRES_DB
127+
LANG: en_US.UTF-8
128+
RACK_ENV: production
129+
RAILS_ENV: production
130+
RAILS_LOG_TO_STDOUT: enabled
131+
RAILS_SERVE_STATIC_FILES: enabled
132+
SECRET_KEY_BASE:
133+
PORT: 5000
134+
POSTGRES_PASSWORD: $POSTGRES_PASSWORD
135+
depends_on:
136+
postgres:
137+
condition: service_healthy
138+
deploy:
139+
resources:
140+
limits:
141+
cpus: '1'
142+
memory: 512M
143+
144+
release:
145+
build:
146+
context: .
147+
command:
148+
- bin/rails db:migrate
149+
environment:
150+
DATABASE_URL: postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@postgres:5432/$POSTGRES_DB
151+
RAILS_ENV: production
152+
SECRET_KEY_BASE:
153+
depends_on:
154+
postgres:
155+
condition: service_healthy
156+
deploy:
157+
resources:
158+
limits:
159+
cpus: '1'
160+
memory: 512M
161+
restart: "no"
162+
```
163+
164+
## Step 2 - Deploying to your cloud account
165+
166+
Now all you need to do is deploy your application to the cloud.
167+
168+
### Deploying to AWS
169+
170+
If you're deploying to AWS, you'll need to invoke `defang compose up` with your AWS access credentials in the environment:
171+
172+
```
173+
AWS_REGION=us-west-2 AWS_PROFILE=default defang compose up --provider aws
174+
```
175+
176+
See our full tutorial on [deploying to AWS](/docs/tutorials/deploy-to-aws).
177+
178+
### Deploying to GCP
179+
180+
GCP support for deployments without Dockerfiles coming soon.
181+
182+
## Step 3 - Migrating your data
183+
184+
:::tip
185+
If you need help with your migration, please reach out to our support team on [Discord](https://s.defang.io/discord).
186+
:::

0 commit comments

Comments
 (0)