December 15, 2015 | Written by: Jeff Sloyer
Share this post:
On the heels of the announcement of a new Bluemix region in Sydney, I thought it would be appropriate to sit down and write a post on migrating your app from one Bluemix region to another. There are a multitude of reasons why I might want to move an app, for example, if I wanted better performance for my users in Australia and Asia by reducing latency.
For this blog post, I am going to migrate a Node.js app that uses a Cloudant database. These steps apply to any app independent of the language, so feel free to reuse these basics for any apps you want to move.
Below are the high-level steps required to migrate your app between regions:
- Setting up the Cloud Foundry command line
- Identify what services your app is using
- Login to the new region
- Create services in new Bluemix region
- Deploy your app to the new Bluemix region
Below are two optional steps:
- Replicate your data to the new Bluemix region
- Redirect your old URL to your new URL (This won’t be covered in this post).
For those who prefer to follow video instruction, please see below:
Watch the video (https://www.youtube.com/watch?v=X3Ge0beEfdI)
Required steps for migrating an app between regions
Again, this post does not cover setting up SSL and setting up a custom domain and performing load balancing and high-availability between Bluemix regions. An upcoming post will go over those topics.
Setting up the Cloud Foundry command line
To get started you will need the CloudFoundry CLI (command line interface) to perform these changes. If you do not have it setup, download the Cloud Foundry CLI tool and run the installer.
Once you have downloaded and installed the CLI, you will need to connect it to the Bluemix region that hosts your app. Below are URLs for the Bluemix API by region:
- US South – https://api.ng.bluemix.net
- London – https://api.eu-gb.bluemix.net
- Sydney – https://api.au-syd.bluemix.net
You will need to login with the CLI to the region that your Bluemix app is currently running in. For example, if my Bluemix app was in US South, I would use the following:
cf login -a https://api.ng.bluemix.net
Identify what services your app is using
Next we will need to determine what services are bound to the app. To do this, you can do this from the Bluemix UI or you can do it from the command line; let’s do it from the command line. For this example, I am referencing an app called talent-manager:
cf services | grep talent-manager
Of course you would want to replace talent-manager
with the name of your application. The command above returns the following:
personality-insights-talent-manager personality_insights standard talent-manager create succeeded
talent-manager-db cloudantNoSQLDB Shared talent-manager create succeeded
In my case, I am using two services—Watson Personality Insights and Cloudant. I will need to setup these services in the new Bluemix region.
Login to the new region
Next, we will need to login to the new region. To get the URL for it, refer to the list of region URLs mentioned earlier. In this case, I want to move my app to au-syd, our new region in Sydney, Australia. To connect to au-syd, I would use the following command:
cf login -a https://api.au-syd.bluemix.net
Once there, I need to re-create my services. For Watson Personality Insights, I would use the following to re-create the service:
cf create-service personality_insights tiered personality-insights-talent-manager
For Cloudant, I would use the following to re-create the service:
cf create-service cloudantNoSQLDB Shared talent-manager-db
Deploy your app to the new Bluemix region
Next, you need to deploy your code to the new region. This simply can be done with
cf push. My application (if you are interested in the source code it’s available in project talent-manager on GitHub) has a
manifest.yml file, so the services will be automatically bound to my new app. If your app doesn’t have a manifest, you can bind your services to your app manually. Let’s go through both cases.
Case #1: Application with a
Now sit back and wait and you will be done!
Case #2: Application without a
cf push <em>myappname</em> --no-start
cf bind <em>myappname</em> talent-manager-db
cf bind <em>myappname</em> personality-insights-talent-manager
cf start <em>myappname</em>
The above seems like a lot, but it really isn’t. Let’s go into what it’s doing. The first command
cf push myappname --no-start
uploads our app code to the new Bluemix region and doesn’t start the app because we need to connect two services to it.
The new two commands (
cf bind myappname talent-manager-db and
cf bind myappname personality-insights-talent-manager) connect the two services and my app.
The last command
cf start myappname starts the application.
That’s basically it. There are a couple more optional steps below that you might consider. With the steps above, you have migrated your app to a new Bluemix region; give yourself a pat on the back!
Optional app migration steps
Since you now have moved your app, what is your app good for without your data? You need to move your data as well. As shown below, if you are using Cloudant, it is pretty easy.
Replicate your data to the new Bluemix region
- Login to the Bluemix Dashboard, click DASHBOARD at the top, and then click on your application tile
- Click on the Cloudant service and take note of the names of your databases
- Click on the “Launch” button in the upper right hand corner
- Click on replication on the left
- Under “Source Database”, type in the name of your database
- Under Target Database, click “New Database”
- Click “Create a new remote database”
- Formulate the URL for your new database (instructions below)
To do this we need to use the Cloud Foundry command line to formulate this
- Run the following, replacing appname with the name of your new application
cf environment <i>myappname</i>
- It it going to return a bunch of data (JSON) on the screen, but we are interested in only 1 line. Under a line that contains
cloudantNoSQLDB we should see a line that has
url in it, example below.You want to copy the value to the right of
"url:", it will start with
https and end in
Make sure you do not copy the
" and the
- Paste the copied value into the browser table that is open to Cloudant Replication for the target database
- At the end of the url that you pasted enter
/mydbname, replacing mydbname with the name of your existing database that you noted earlier
The final URL should looking something like this (with your db name and usernames and passwords being different, don’t worry the credentials below don’t work):
- Click “Replicate”
- Go back to the tab with the Bluemix Dashboard and click “Overview” in the top left
- At the bottom left side of the box for the Cloudant Service click “Show Credentials”
- Copy the value next to
"password:", don’t copy the
" or the
The value you copied should look like something below:
- Go back to the Cloudant Replication tab, paste in the password and click “Continue”
The time required to copy from the old database to the new one will depend on how much data you have in your database.
Redirect your old URL to your new URL
As a reminder, you may need redirection from your old app to your new app. For example, from
http://myapp.au-syd.mybluemix.net. The redirection won’t be covered in this post, but basically you just need to do a
301 redirection. A
301 is a permanent redirection.
A proper production application would be using a load balancer and custom domain; in this situation you would not have to setup redirection, as you would just need to update your DNS
A records for your application. Again, instructions on this will be provided in a future blog post.
I would love to hear your feedback and any suggestions you have, please reach out to me on Twitter @jsloyer.