Deployments and Rollbacks

By default OpenShift applications prepare, distribute, and activate deployments on every git push. Alternatively, a user may choose to disable automatic deployments and use the 'rhc deployment' set of commands to fully control the deployment lifecycle. Use these commands to deploy manually from a git reference or from a binary file, list and display deployments and also activate existing deployments.

In This Guide

Configuring How Many Deployments to Keep

By default, OpenShift keeps one (1) deployment, the one that is currently being used to serve your application. You can see this by sshing into your application using the rhc app ssh <appname> command and then listing the contents of the ~/app-deployments folder.

$ rhc ssh myapp -n osexample
Connecting to 54da3b4be0b8cd64a2000010@myapp-osexample.rhcloud.com ...

[myapp-osexample.rhcloud.com <UUID>]\> ls -lah ~/app-deployments/
total 24K
drwxr-xr-x.  6 <UUID> <UUID> 4.0K Feb 11 13:41 .
drwxr-x---. 15 root   <UUID> 4.0K Feb 10 12:10 ..
drwxr-x---.  5 <UUID> <UUID> 4.0K Feb 11 13:41 2015-02-11_13-41-25.320
drwxr-xr-x.  2 <UUID> <UUID> 4.0K Feb 11 13:41 by-id
lrwxrwxrwx.  1 <UUID> <UUID>   23 Feb 11 13:41 current -> 2015-02-11_13-41-25.320

You can change the number of deployments that are kept for your application by using the rhc app-configure <app> --keep-deployments <number> command, where <number> is the number of deployments to keep.

$ rhc app-configure <app> --keep-deployments <number>  # 1 is the Default
$ rhc app-configure myapp --keep-deployments 5
Configuring application 'myapp' ... done

myapp @ http://myapp-osexample.rhcloud.com/ (uuid: 54da3b4be0b8cd64a2000010)
----------------------------------------------------------------------------
  Deployment:        auto (on git push)
  Keep Deployments:  5
  Deployment Type:   git
  Deployment Branch: master

Your application 'myapp' is now configured as listed above.

Keeping more deployments will allow you to easily roll back to a previous version of your code if you happen to make a mistake. Each deployment that you keep is a complete copy of your code and takes up additional space on your gear. So if your code base is 5MB, and you keep 5 deployments, that is 25MB of space that will be used.

Configuring Which Branch to Deploy

By default OpenShift deploys the master branch when you do a git push (when automatic deployments are enabled). You can change this behavior using the rhc app-configure <app> --deployment-branch <branch_name> command, where <branch_name> is the new branch to deploy.

$ rhc app-configure <app> --deployment-branch <branch_name>  # Master is the Default
$ rhc app-configure myapp --deployment-branch new_branch
Configuring application 'myapp' ... done

myapp @ http://myapp-osexample.rhcloud.com/ (uuid: 54da3b4be0b8cd64a2000010)
----------------------------------------------------------------------------
  Deployment:        auto (on git push)
  Keep Deployments:  5
  Deployment Type:   git
  Deployment Branch: new_branch

Your application 'myapp' is now configured as listed above.

Now when you make commits to your new branch and do a git push to OpenShift, those changes will be deployed.

Enabling/Disabling Automatic Deployments

OpenShift automatically deploys a new version of your application when you do a git push. To disable this behavior and manage the lifecycle of your application manually you can use the rhc app-configure <app> --no-auto-deploy command.

$ rhc app-configure <app> --no-auto-deploy  # Disable Auto Deploy
$ rhc app-configure myapp --no-auto-deploy
Configuring application 'myapp' ... done

myapp @ http://myapp-osexample.rhcloud.com/ (uuid: 54da3b4be0b8cd64a2000010)
----------------------------------------------------------------------------
  Deployment:        manual (use 'rhc deploy')
  Keep Deployments:  5
  Deployment Type:   git
  Deployment Branch: master

Your application 'myapp' is now configured as listed above.

Once you have issued the rhc app-configure <app> --no-auto-deploy command, deployments will NOT be created automatically when you do a git push. You will have to deploy manually using the rhc deploy command.

If you decide in the future that you don’t need to manually deploy your application, you can re-enable automatic deployments with the rhc app-configure <app> --auto-deploy command.

$ rhc app-configure <app> --auto-deploy     # Enable Auto Deploy (enabled by default)
$ rhc app-configure myapp --auto-deploy
Configuring application 'myapp' ... done

myapp @ http://myapp-osexample.rhcloud.com/ (uuid: 54da3b4be0b8cd64a2000010)
----------------------------------------------------------------------------
  Deployment:        auto (on git push)
  Keep Deployments:  5
  Deployment Type:   git
  Deployment Branch: master

Your application 'myapp' is now configured as listed above.

Using the Deploy Command

If you have used the rhc app-configure <app> --no-auto-deploy command to configure your application not to use the auto-deploy feature, then you will have to manage your applications lifecycle manually using the rhc deploy <ref> -a <app> command.

$ rhc deploy <ref> -a <app>

There are a couple of different ways that you can use this command to deploy your application.

Option 1

The first option is to use the name of the git branch that you want to deploy from. Doing this will always use the most recent commit.

$ rhc deploy <branch_name> -a <app>

After you run this command, the normal deployment procedures will take over, and a new deployment will be created (which you can see using the rhc deployment list command). The second option is to use the SHA1 reference from a previous deployment.

Option 2

$ rhc deploy <SHA1> -a <app>

Finding the SHA1 reference that you need can be a little tricky, so I have detailed the steps below.

First you need to get the <deployment_id> of the deployment that you want to activate, which is the series of numbers and letters in the far right column when you use the rhc deployment list command.

$ rhc deployment list -a myapp
1:06 PM, deployment 77759728
1:07 PM, deployment 36467560
1:11 PM, deployment 5accbef4

Next, you need to view the details of the deployment that you have selected using the rhc deployment show <deployment_id> -a <app> command.

$ rhc deployment show 36467560 -a myapp
Deployment ID 36467560 (inactive)
---------------------------------
  Git Reference:     master
  SHA1:              15577d3
  Created At:        1:07 PM
  Hot Deploy:        false
  Force Clean Build: false
  Activations:       1:07 PM

Use 'rhc show-app myapp --configuration' to check your deployment configurations.

Now you can use the series of numbers and letters next to the SHA1 heading to activate the deployment that you have selected using the rhc deploy <ref> -a <app> command.

$ rhc deploy 15577d3 -a myapp
Deployment of git ref '15577d3' in progress for application myapp ...
Stopping PHP 5.4 cartridge (Apache+mod_php)
Waiting for stop to finish
Waiting for stop to finish
Building git ref '15577d3', commit 15577d3
Checking .openshift/pear.txt for PEAR dependency...
Preparing build for deployment
Deployment id is 38e50c3a
Activating deployment
Starting PHP 5.4 cartridge (Apache+mod_php)
Application directory "/" selected as DocumentRoot
Success

And now you can see that a new deployment was created

$ rhc deployment list -a myapp
1:07 PM, deployment 36467560
1:11 PM, deployment 5accbef4
1:13 PM, deployment 38e50c3a

Configuring a Deployment Type

OpenShift offers you two ways to deploy your application, using git push, or by deploying a pre-compiled binary archive of your application. You can configure which version your application will use by using the rhc app-configure <app> --deployment-type <git|binary> command.

$ rhc app-configure <app> --deployment-type <git|binary>  # Git is the default

To learn more about how to use binary deployments, you can visit this link.

Creating a Deployment

Every time you do a git push to your application (while auto-deploy is enabled) a new deployment is created, stored, and deployed on the server.

Once you reach the limit that you have configured with the rhc app-configure <app> --keep-deployments <number> command, the oldest deployment will be deleted when a new one is created.

$ git commit -am "I made some updates"
$ git push
$ touch new_feature.php
$ git add new_feature.php
$ git commit -am "adding a new feature"
[master 15577d3] adding a new feature
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 new_feature.php
$ git push
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 238 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)
remote: Stopping PHP 5.4 cartridge (Apache+mod_php)
remote: Waiting for stop to finish
remote: Waiting for stop to finish
remote: Building git ref 'master', commit 15577d3
remote: Checking .openshift/pear.txt for PEAR dependency...
remote: Preparing build for deployment
remote: Deployment id is 267b0817
remote: Activating deployment
remote: Starting PHP 5.4 cartridge (Apache+mod_php)
remote: Application directory "/" selected as DocumentRoot
remote: -------------------------
remote: Git Post-Receive Result: success
remote: Activation status: success
remote: Deployment completed with status: success
To ssh://54da3b4be0b8cd64a2000010@myapp-osexample.rhcloud.com/~/git/myapp.git/
   8cd8a7e..15577d3  master -> master

Listing Deployments

To view the list of available deployments that have been created for your application, you can use the rhc deployment list command. This will print out a list of the time that the deployment was created, along with the deployment id (which you will need for the rhc deployment show and rhc deployment activate commands.

$ rhc deployment list -a <app>
$ rhc deployment list -a myapp
12:04 PM, deployment ca074ed0
12:17 PM, deployment 7377672b
12:51 PM, deployment 42b61025
12:53 PM, deployment fd24e90a

Viewing Individual Deployment Details

To view details about a specific deployment, you can use the rhc deployment show <deployment_id> -a <app> command. It will show you the git branch that was used, the git commit hash, when it was created, when it was activated, and whether or not the hot deploy or clean build markers were used. You will need to use this command to find the information needed for the rhc deploy command if you disable auto-deploy.

$ rhc deployment show <deployment_id> -a <app>
$ rhc deployment show 42b61025 -a myapp
Deployment ID 42b61025 (inactive)
---------------------------------
  Git Reference:     master
  SHA1:              6b284d4
  Created At:        12:51 PM
  Hot Deploy:        false
  Force Clean Build: false
  Activations:       12:51 PM

Activating a Deployment

Activating a deployment is easy, just use the rhc deployment activate <deployment_id> -a <app> command, where <deployment_id> is the id that you got from running the rhc deployment list command.

$ rhc deployment activate <deployment_id> -a <app>

When you activate a deployment, your application will go through the same activation process that it would use if you had auto-deploy enabled and did a git push, as you can see below.

$ rhc deployment activate 42b61025 -a myapp
Activating deployment '42b61025' on application myapp ...
Activating deployment
Stopping PHP 5.4 cartridge (Apache+mod_php)
Waiting for stop to finish
Waiting for stop to finish
Starting PHP 5.4 cartridge (Apache+mod_php)
Application directory "/" selected as DocumentRoot
Success

Rolling Back a Deployment

Rolling back to a previous deployment uses the same rhc deployment activate <deployment_id> -a <app> command, and activates the same deployment process.

$ rhc deployment activate <deployment_id> -a <app>

Here you can see that we are rolling back to a previous deployment, and the deployment process has been activated.

$ rhc deployment activate 42b61025 -a myapp
Activating deployment '42b61025' on application myapp ...
Activating deployment
Stopping PHP 5.4 cartridge (Apache+mod_php)
Waiting for stop to finish
Waiting for stop to finish
Starting PHP 5.4 cartridge (Apache+mod_php)
Application directory "/" selected as DocumentRoot
Success

As you can see, when we ran the rhc deployment activate 42b61025 -a myapp command fd24e90a was the active deployment, and we rolled back to 42b61025, which is now listed as the most current deployment.

$ rhc deployment list -a myapp -n osexample
12:04 PM, deployment ca074ed0
12:17 PM, deployment 7377672b
12:51 PM, deployment 42b61025
12:53 PM, deployment fd24e90a (rolled back)
1:14 PM, deployment 42b61025 (rollback to 12:51 PM)

Deleting Old Deployments Manually

If you would like to manually clean up old deployments that are taking up space you just need to run the rhc app-configure myapp --keep-deployments command and specify a lower number of deployments to keep. But running this command does not delete the old deployments right away, you have to re-trigger the deployment process by committing a change and doing a git push, then the old deployments will be deleted, and only the number that you have currently specified will be kept.

You can see here that our application currently has 5 deployments that are being stored on our gear.

$ rhc deployment list -a myapp
12:17 PM, deployment 7377672b
12:51 PM, deployment 42b61025
1:14 PM, deployment 42b61025
1:18 PM, deployment 3557daf0
1:19 PM, deployment 267b0817

Here we are specifying that we only want to keep 3 deployments now.

$ rhc app-configure myapp --keep-deployments 3
Configuring application 'myapp' ... done

myapp @ http://myapp-osexample.rhcloud.com/ (uuid: 54da3b4be0b8cd64a2000010)
----------------------------------------------------------------------------
  Deployment:        auto (on git push)
  Keep Deployments:  3
  Deployment Type:   git
  Deployment Branch: master

Your application 'myapp' is now configured as listed above.

Use 'rhc show-app myapp --configuration' to check your configuration values any time.

Here you can see that even though we changed the keep deployments to 3, there are still 5 being stored.

$ rhc deployment list -a myapp
12:17 PM, deployment 7377672b
12:51 PM, deployment 42b61025
1:14 PM, deployment 42b61025
1:18 PM, deployment 3557daf0
1:19 PM, deployment 267b0817

Now we create a new file, do a git commit and a git push, and it goes through the deployment process again.

$ touch updated_feature.php
$ git add updated_feature.php
$ git commit -am "updating a feature"
[master 3d4206e] updating
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 testing
$ git push
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 249 bytes | 0 bytes/s, done.
Total 2 (delta 1), reused 0 (delta 0)
remote: Stopping PHP 5.4 cartridge (Apache+mod_php)
remote: Waiting for stop to finish
remote: Waiting for stop to finish
remote: Building git ref 'master', commit 3d4206e
remote: Checking .openshift/pear.txt for PEAR dependency...
remote: Preparing build for deployment
remote: Deployment id is 2fe905e6
remote: Activating deployment
remote: Starting PHP 5.4 cartridge (Apache+mod_php)
remote: Application directory "/" selected as DocumentRoot
remote: -------------------------
remote: Git Post-Receive Result: success
remote: Activation status: success
remote: Deployment completed with status: success
To ssh://54da3b4be0b8cd64a2000010@myapp-osexample.rhcloud.com/~/git/myapp.git/
   15577d3..3d4206e  master -> master

And now we only have 3 deployments being stored for our application.

$ rhc deployment list -a myapp
1:18 PM, deployment 3557daf0
1:19 PM, deployment 267b0817
1:41 PM, deployment 2fe905e6