Note: This guide uses the Cloud Foundry CLI version 5. The instructions below are not compatible with any cf version > 5. Click here to get a description of the differences between CLI v5 and CLI v6.

In some cases it is necessary to run certain admin tasks (also known as One-Off commands). These tasks get executed in the context of the application and thus have access to all databases and services bound to the application as well as to the application’s source code. The purpose of these tasks could be a database migration, wich requires the execution of "rake db:migrate" or "manage.py syncdb" inside your application directory. For this use case anynines provides the "cf console [appname]" command. Running this command will provide you access to a Rails Console. The drawback of the “cf console” command is that it is very framework specific and as such does not work for every framework.

You might know that anynines is build on top of Cloud Foundy which is an Open Source PaaS. There is ongoing work to provide a mechanism to run arbitrary commands, much like in every SSH console. Thankfully you don't have to wait untill the Cloud Foundry team has completed this feature. The instructions below should show you how to run these tasks for the time being.

1. Deploy your application

git clone git@github.com:anynines/simple_rails_app.git
cd simple_rails_app 
cf push

The “cf push” command will ask you some questions concerning your deployment setup. Have a look at the Getting Started guide for a detailed description. When asked if you would like to save the configuration, please answer with “yes”. This will to generate a deployment manifest file (manifest.yml).

2. Add a helper application to your codebase 

In the next step we will deploy a dedicated application instance where your admin tasks will be executed. To enable this instance receiving your commands we need a helper application. To setup the helper application make sure you are in your local application directory and type:

git clone https://github.com/jbayer/websocketd-cloudfoundry.git 
wget http://download.websocketd.com/releases/websocketd/0.2.8/linux_amd64/websocketd -P websocketd-cloudfoundry
chmod +x websocketd-cloudfoundry/websocketd

3. Extend the deployment manifest with a second application

Next we will deploy a second application instance. In order to do that we have to add a second application to our deployment manifest:

---
applications:
- name: simple_rails_app
  memory: 256M
  instances: 3
  host: simple_rails_app_wss_console
  domain: aws.ie.a9sapp.eu
  path: .
  services:
    mysql-53e8:
      label: mysql
      provider: core
      version: '5.5'
      plan: Pluto-free
- name: simple_rails_app-one-off-instance
  memory: 256M
  instances: 1
  host: simple_rails_app_wss_console-uu6yxv63fnqf9t5phitb78pn
  domain: aws.ie.a9sapp.eu
  command: /app/websocketd-cloudfoundry/websocketd --port=$PORT --dir=/app/websocketd-cloudfoundry --devconsole
  path: .
  services:
    mysql-53e8:
      label: mysql
      provider: core
      version: '5.5'
      plan: Pluto-free

Make sure the second application is connected to the same service instances as the main application (in this case mysql-53e8). Then pick a cryptic host for this second application, to prevent unauthorized access. Note that the second application uses a custom start command.

!! Important: Replace the host of the second application and add a string of numbers and characters to the host name (like the ‘uu6yxv63fnqf9t5phitb78pn’ in the example below). Doing so will make sure only people knowing the host will be able to run admin tasks.

4. Deploy the one-off instance and open it in your browser

After extending the deployment manifest we just have to push our second application with:

cf push simple_rails_app-one-off-instance

As soon as the one off instance is running you will be able to open up a command line in your web browser. To do so, enter the URL of the application and add the port suffix ":10000" as well as the "/bash.sh" ending. Note that you have to replace the host to the one you picked in the manifest file.

After clicking on the tick in the top left corner your will be able to type your commands into the browser:

4. Shut down the one-off-instance 

After you’ve finished your administrative tasks you can delete the "one-off-instance" application to avoid a waste of recourses. In case you need it again you just have to execute step three of this guide, since the one-off-instance is still configured in your manifest. To avoid the one-off-instance to be pushed every time you push your main application, just type “cf push” plus the name of your actual application:

cf push simple_rails_app

5. Hint for Ruby on Rails developers 

If you are deploying a rails application with ruby  version >= 2.0.0 you may experience the following error when running bundle exec rails c:

/home/vcap/app/vendor/ruby-2.0.0/lib/ruby/2.0.0/irb/completion.rb:9:in `require': libreadline.so.5: cannot open shared object file: No such file or directory - /home/vcap/app/vendor/ruby-2.0.0/lib/ruby/2.0.0/x86_64-linux/readline.so (LoadError)

In this case add the following gem to your Gemfile:

gem 'rb-readline'