9.8 KiB
| tags | title | excerpt | layout | permalink | ||
|---|---|---|---|---|---|---|
|
Multi-Machine Workspaces in Che | tutorials | /:categories/multi-machine/ |
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. Start Che
Use your SaaS account for the following, or if you have installed Che, open a terminal and use the Che startup script:
# Launch Che
che start\
When you execute this command, you'll see the URL for the Che server.
This URL can be used to open Che server's dashboard. It is where you manage your projects and workspaces.
2. Create Workspace
Click the "Dasboard" menu item in the dashboard. Click the "New Workspace" button if there are existing workspaces or make sure "Select Source" category is set to "New from blank, template, or sample project" if one or more workspace exists.  Select "Java-MySQL" from the list of available stacks.  The other workspace information can remain as it is. Click the "create" button at the bottom 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. Note that it is not required to know the database listed for this tutorial. 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. Give the server ample amount of time to start as the server output may stay on INFO Version - HCANN000001: Hibernate Commons Annotations {4.0.5.Final} for awhile. 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
Che 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 it's 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 the "codenvy/mysql" 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.
services:
db:
image: codenvy/mysql
environment:
MYSQL_DATABASE: petclinic
MYSQL_USER: petclinic
MYSQL_PASSWORD: password
mem_limit: 1073741824
dev-machine:
image: codenvy/ubuntu_jdk8
mem_limit: 2147483648
depends_on:
- 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 it's MySQL client connection in the projects source code at src/main/resources/spring/data-access.properties. 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 operations perspective interface provides the external ephemeral ports assigned by docker for all machines' exposed ports. Image below indicates only external ephemeral port 32800 assigned to "db" machine's exposed port 3306.  The "db" machine contains a MySQL database created by the Docker image "codenvy/mysql". Taking a closer look at the "codenvy/mysql" image Dockerfile's entry point script will show how the "db" machine configures the MySQL server at the workspace startup.
FROM alpine:3.4
EXPOSE 3306/tcp
ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ADD entrypoint.sh /
CMD mkdir /docker-entrypoint-initdb.d
CMD ln -s /usr/local/bin/docker-entrypoint.sh /entrypoint.sh # backwards compat
........
CMD ["mysqld"]
........
VOLUME /var/lib/mysql
ENTRYPOINT ["docker-entrypoint.sh"]
The "docker-entrypoint.sh" script shown partly below uses environment variables to configure the MySQL server. In this stack's compose recipe, shown above, environment variables set the MySQL database's name and user/password information that is referenced in the "db" machine's entry point script ($MYSQL_DATABASE, $MYSQL_USER, and $MYSQL_PASSWORD).
#!/bin/bash
.....
if [ ! -z "$MYSQL_RANDOM_ROOT_PASSWORD" ]; then
MYSQL_ROOT_PASSWORD="$(pwgen -1 32)"
echo "GENERATED ROOT PASSWORD: $MYSQL_ROOT_PASSWORD"
fi
"${mysql[@]}" <<-EOSQL
-- What's done in this file shouldn't be replicated
-- or products like mysql-fabric won't work
SET @@SESSION.SQL_LOG_BIN=0;
DELETE FROM mysql.user ;
CREATE USER 'root'@'%' IDENTIFIED BY '${MYSQL_ROOT_PASSWORD}' ;
GRANT ALL ON *.* TO 'root'@'%' WITH GRANT OPTION ;
DROP DATABASE IF EXISTS test ;
FLUSH PRIVILEGES ;
EOSQL
if [ ! -z "$MYSQL_ROOT_PASSWORD" ]; then
mysql+=( -p"${MYSQL_ROOT_PASSWORD}" )
fi
if [ "$MYSQL_DATABASE" ]; then
echo "CREATE DATABASE IF NOT EXISTS \`$MYSQL_DATABASE\` ;" \
| "${mysql[@]}"
mysql+=( "$MYSQL_DATABASE" )
fi
if [ "$MYSQL_USER" -a "$MYSQL_PASSWORD" ]; then
echo "CREATE USER '$MYSQL_USER'@'%' IDENTIFIED BY \
'$MYSQL_PASSWORD' ;" | "${mysql[@]}"
if [ "$MYSQL_DATABASE" ]; then
echo "GRANT ALL ON \`$MYSQL_DATABASE\`.* TO \
'$MYSQL_USER'@'%' ;" | "${mysql[@]}"
fi
echo 'FLUSH PRIVILEGES ;' | "${mysql[@]}"
fi
.....
exec "$@"