Multi-Machine Workspaces

A multi-machine recipe allows multiple runtimes to communicate/share data. In this tutorial we will be looking at an existing Java and MySQL application called Pet Clinic. The tutorial will help show how to create a multi-machine from an existing runtime stack called “Java-MySQL”, execute commands on different target runtimes, startup the Pet Clinic Tomcat server, view/interact with the Pet Clinic web page, and take a closer look at the “Java-MySQL” runtime stack /runtime recipe to get a better understanding of how multi-machine runtimes are created.

1. Pre-Reqs

Use your account for the following or if you are using Codenvy refer to the getting started documentation

2. Create Workspace

Click the “Dashboard” menu item in the dashboard. Click the “Create Workspace” button if there are existing workspaces.


Select “Multi Machine” section and “Java-MySQL” stack from the list of available stacks.


The other workspace information can remain as it is. Click the “create” button at the bottom or at the right top to create the workspace.


3. Using IDE

Once the workspace is created, the IDE will be loaded in the browser.

Each runtime can be identified in the processes section of the IDE. It will list the runtimes of “dev-machine” and “db” of our multi-machine workspace. The “db” runtime for this tutorial provides the database for the Java Spring application to use.

To make sure that the database is running we will issue the “show database” command to the “db” runtime. Select the “db” runtime item from the target drop down menu. Then make sure that “show databases” is selected in the command drop down menu and hit the play button.


This will run the “show databases” command in the “db” runtime and display the available database at the bottom in the processes section. Note that it is not required to know the database listed for this tutorial and this step merely shows how to successfully target different runtimes.

Switch the target back to “dev-machine”, select the “web-java-petclinic: build and deploy” command, and click the play button. The Pet Clinic Java code will be compiled and the tomcat server started. The tomcat server when it is ready will output Server startup in <time> ms. Click on the preview url link after the tomcat server is started to open the Pet Clinic web page.


The web page can interact in various ways with the database. Data can be added to the data by clicking the “Find owner” link, clicking the “Add owner” link, and filing in the form.


4. Editing, Building and Debugging

Codenvy is a fully featured IDE that just happens to be in the browser. You can explore the editor which includes intellisense for some languages and refactoring. It also includes git and svn support built-in.

The example app has built in commands for building and running the app. You can also debug right inside Che.

5. About Docker and Compose

Read this section to understand more about the multi-machine “Java-MySQL” runtime stack used and its runtime recipe. The “Java-MySQL” stack configuration is located in the “stacks” section in the dashboard. This stack can be found easier by typing “java” in the filter form.


Click on the “Java-MySQL” menu item which will bring up the stack’s configuration page. There is various useful configuration information provided on this page as well as the Runtime Stacks and Runtime Recipes documentation pages. For this tutorial, we will be focusing on the recipe configuration and dockerfile provided in the “Java-MySQL” stack.

The recipe uses docker compose syntax. Due to the limitation of the JSON syntax the compose recipe is written as a single line with \n indicating carriage return. The following is the recipe in expanded form to make reading easier.

  image: mysql
   MYSQL_DATABASE: petclinic
   MYSQL_USER: petclinic
   MYSQL_PASSWORD: password
  mem_limit: 1073741824
  image: eclipse/ubuntu_jdk8
  mem_limit: 2147483648
    - db

Examining the code above you will see our two runtime machines “db” and “dev-machine”. Every workspace requires a machine named “dev-machine”.

In the recipe the depends_on parameter of the “dev-machine” allows it to connect to the “db” machine MySQL process’ port 3306. The “dev-machine” configures its MySQL client connection in the projects source code at src/main/resources/spring/ The url is defined by jdbc.url=jdbc:mysql://db:3306/petclinic which uses the database machine’s name “db” and the MySQL server default port 3306.

Port 3306 is exposed in the “db” machines Dockerfile during build but is not required for “dev-machine” to connect to it. Exposing port 3306 is done to provide access to database that is external to “db” machine network via a random ephemeral port assigned by docker. The “dev-machine” by setting depends_on: - db creates a private network that allows it use of “db” machine’s name as hostname and port 3306 without having to determine the ephemeral port docker assigned.

Exposing port 3306 is done to provide an option for an external administrator to log into the “db” machine MySQL server through a MySQL client on the ephemeral port assigned. The workspace runtime configuration interface provides the external ephemeral ports assigned by docker for all machines’ exposed ports. Image below indicates only external ephemeral port 32778 assigned to “db” machine’s exposed port 3306.


The “db” machine contains a MySQL database created by MySQL’s official Docker image “mysql”. Within MySQL runtime information for the “db” machine there are four environment variables set that are used by MySQL docker image’s entrypoint script that sets the database name and authentication information.