Note: This guide uses the Cloud Foundry CLI version 6. The instructions below are not compatible with any cf version < 6. Click here to read how to install the cf CLI v6.

Every now and then you might need to run 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.

anynines is build on top of Cloud Foundy which is an Open Source PaaS (Platform as a Service). 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. Setup a demo application

Clone the demo application and push it to run on anynines:

$ git clone git@github.com:anynines/simple_rails_app.git
$ cd simple_rails_app 
$ cf push simple-rails-app 
$ cf create-service mysql Pluto-free simple-rails-app-mysql-service
$ cf bind-service simple-rails-app simple-rails-app-mysql-service
$ cf restart simple-rails-app

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. Deploy an one-off instance of your application

$> cf push simple-rails-app-one-off-instance -n simple_rails_app_wss_console-uu6yxv63fnqf9t5phitb78pn -c '/app/websocketd-cloudfoundry/websocketd --port=$PORT --dir=/app/websocketd-cloudfoundry --devconsole'
$> cf bind-service simple-rails-app-one-off-instance simple-rails-app-mysql-service

!! Important: Replace the host in the first command (the -n option) 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.

Furthermore you will have to bind all services which are bound to the original application to the one-off instance. In this example this is only the MySQL service.

4. Open the one-off instance in your browser

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:

Attention: After you've finished the administrative work you have to stop the one-off-instance so that nobody else can access your applications. Have a look at step 4 to learn how to do so.

4. Shut down the one-off-instance

After you’ve finished your administrative tasks you can delete or stop the "one-off-instance" application to avoid a waste of recourses. In case you need it again you just fire it up again!

$ cf stop simple-rails-app-one-off-instance

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'