We removed our free Sandbox April 25th.
You can read more on our blog.



CLI Command examples on this page are always provided without the --application (shorthand -A) argument, assuming you’re running these commands in a connected folder (at creation or using the dotcloud connect command). For more details on connected folders, see Migrating to the CLI 0.9.

The java service can host any kind of application based on java.servlet.

This makes it suitable not only for “barebones” servlets, but also many frameworks and languages, including (but not limited to):

  • Clojure
  • Grails
  • JRuby on Rails
  • Lift
  • Play!
  • Scala
  • and a lot more

Most ready-to-use applications will also run fine. You can generally assume that if it ships as a WAR [1] file, it will run on dotCloud.

Basic Use

Let’s assume that you are building a dotCloud application called “ramen”. For the sake of simplicity, we will also assume that everything related to this application is located in a directory called “ramen-on-dotcloud”.

Let’s setup our environment:

mkdir ramen-on-dotcloud
cd ramen-on-dotcloud
dotcloud create ramen

A dotCloud application is described by a Build File (dotcloud.yml), which is a simple YAML file named “dotcloud.yml” located in our “ramen-on-dotcloud” directory. To add a new service to our app, we just add the following lines to “ramen-on-dotcloud/dotcloud.yml”:

  type: java
  approot: hellojava

This Build File tells the dotCloud platform that the code (or the WAR file) for this service will be located in the “hellojava” directory.

If you are not deploying multiple services, you can omit the approot directive, and put your WAR files in the same directory as dotcloud.yml.

After copying your WAR file into the ramen-on-dotcloud directory, your app is ready.

We can now push our application to dotCloud:

dotcloud push

URLs will be generated for each web service in our application. Open your browser to see your new service in action!

If you want to attach a better URL to your application, read the Custom Domains documentation.

Advanced Configuration

You can modify some advanced parameters of the Java configuration from your “dotcloud.yml”:

  type: java
    java_initial_heap_size: 64
    java_maximum_heap_size: 128
    java_maximum_permgen_size: 64
    jetty_version: jetty-6
    java_version: java-6

Let’s see what each setting does:

  • java_initial_heap_size: this option controls the initial size (in megabytes) of the memory allocation pool of the JVM;
  • java_maximum_heap_size: this option controls the maximum size of the memory allocation pool of the JVM (keep in mind that this is not changed when you vertically scale);
  • java_maximum_permgen_size: this option controls the maximum size of the memory pool allocated by the JVM to store class files, you might need to change this for large applications;
  • jetty_version: this option lets you specify which jetty version you want to use. Options are jetty-6, jetty-7, and jetty-8. Default is jetty-6;
  • java_version: this option controls which java version you will be using with this service. Options are java-6, and java-7. Default is java-6. java-7 only works with the following jetty_version‘s jetty-7 and jetty-8.

New settings are applied on the next push.

Java and Jetty Versions

The java service lets you decide which java and jetty versions you want to use with your application. It currently supports Java 1.6, and Java 1.7. It also supports Jetty 6, 7 and 8.


Java 1.7 only works with Jetty 7 and 8. The default settings are Java 1.6 and Jetty 6. To learn how to configure these options, see the the Advanced Configuration section.


The java servlet is served by Jetty. For most purposes, it will be 100% compatible with other application servers like Tomcat.

If you upload a WAR file named thing.war, it will come up as http://...dotcloud.com/thing/. To host your application directly at the top of the URL hierarchy, name it ROOT.war.

If you push an unpacked WAR, and want to host it at the root of your service, you should place your code (i.e. the WEB-INF directory and everything) in a directory called ROOT.

Note that while you can push your apps as unpacked WAR files, it is not recommended to do so, since some class loading mechanisms work better when your app ships as a WAR file.