Setting up your development/deployment environment for COMP9322 Setting up your development/deployment environment for COMP9322 Introduction This exercise will guide you through preparing some software packages that are required for future lab exercises and assignments. In COMP9322, we will create two separate environments: development and deployment. In these labs, we will first set up the development environment, then look into creating your own deployment environment. In development, essentially, you use your own computer (Mac, Windows or Linux, your laptop, PC, or CSE lab machines) to develop the code/project. However, it is easier for everybody involved in this course to have a common development platform that contains a common set of tools. For this reason, we define 'COMP9322 standard development environment' to develop your lab/assignment solutions in. The deployment environment will be mostly based on the development environment we setup in this lab. However, to get a taste of deploying your solution onto a physically different runtime/production environemnt (we commonly call this a 'production server'), we will use Docker for the deployement environment. Docker is a lightweight opensource framework which is used for developing, shiping and running applications. In all lab exercises from here on, we assume that you will be working in your development environment and deploy the applications to the deployment environment. Part 1: Preparation (what you already have from COMP9321) To make the instructions more readable, the ~ character will be used to denote your CSE home directory. When you are asked to issue commands, you should do so from a Terminal session. The $ symbol will be used to mean the prompt you see in the Terminal. You should be able to apply these instructions to your own OS environment. All lab instructions we provide here can be easily translated to Windows, Mac and Linux. NOTE - For Java, Eclipse IDE and Tomcat Server, we are not going to give you detailed instructions here, as you are already familiar with them from COMP9321. However, if you have any problem following these instructions in your own computer, just come to the lab consultations or post a question on the messageboard. There will be help available. Create ~/cs9322-Prac To avoid compatibility issues, what I recommend is for everybody to use the 9322 standard software tool set we specify here -- AND to install the tools under the directory called cs9322-Prac under your home directory. For example, mine is: /Users/hpaik/cs9322-Prac/ (under a Mac). Let's call this $9322_PRAC$. (i.e., `~/cs9322-Prac') NOTE: If you do not have copies of Eclipse or Tomcat on your machine, this lab guide will ask you to install them under $9322_PRAC$. You may have Tomcat, Eclipse, etc. running in your environment already, then I'd recommend re-installing them under $9322_PRAC$, using the exact versions recommended by the lab instructions, even if that means you are duplicating the installation. If you are absolutely against this, make sure that the versions you keep are identical to what we are using here. The starting list included in the 9322 standard software tool set are: Apache Tomcat 8.0.32 Maven 3.2.9 Eclipse IDE - Luna Java Version We use Java 1.7 (no Java 1.8 please). If you have multiple versions of Java installed on your machine, make sure that you have JAVA_HOME set to Java 1.7 distribution. How to do this will be different depending on your environment. If you are not sure, either post a question on the messageboard or come and see me for help. If you are using Mac, the following little trick will allow you to switch JAVA_HOME easily. Put this in your ~/.profile.
#set JAVA_HOME (-v get the version you want)
export JAVA_HOME=$(/usr/libexec/java_home -v 1.7)
Eclipse IDE (Luna) Eclipse Luna is one of the 9322 standard software tool set. We use J2EE developer package of Eclipse. Luna is not the latest version, but it is compatible with Java 1.7. CSE Lab recently has been upgraded to Eclipse Luna. Eclipse Luna, you can find the link here. Eclipse Luna Download page On the page, look for Eclipse IDE for Java EE Developers and suitable distribution for your environment. Download the file and install Luna under $9322_PRAC$. Quick configuration of Eclipse Luna. Create a directory called workspace under $9322_PRAC$ (i.e., $9322_PRAC$/workspace). When the Eclipse starts, set the above workspace as your default workspace for this Eclipse. Go to Menu, Preferences, then Java. Set compiler level to 1.7. Set Installed JRE to JDK 1.7 in your own environment. Choose 1.7 as default (i.e., ticked). Tomcat Server (v8.0.32) Apache Tomcat version 8.0.32 is one of the 9322 standard software tool set. If you have setup Tomcat from the COMP9321 course. You can leave the setup as-is and create a new installation for this course. You can find the Tomcat 8 binary distributions here. Tomcat 8.0.32 Download Download Tomcat 8 and install it under $9322_PRAC$. Just make sure that you have the important environment variables: CATALINA_BASE and CATALINA_HOME set as expected. For example, mine is set to (using my own $9322_PRAC$):
export CATALINA_BASE=/Users/hpaik/cs9322-Prac/apache-tomcat-8.0.32
export CATALINA_HOME=/Users/hpaik/cs9322-Prac/apache-tomcat-8.0.32
Set these values to your own environment. Again, how to set these values is different depending on which computing environment you are using. If you are not sure, post a message or come to me. After installing, start and stop the server to make sure that everything is OK. Part 2: Installing Apache Maven and Eclipse Maven Plug-in For the Web service development exercises, we will use Apache Maven and Apache CXF as main tools. In this part of the lab, we will first setup Mavan, as Apache CXF uses it heavily! Installing and setting up Maven Maven version 3.3.9 is one of the 9322 standard software tool set. Maven is a popular build/project management tool. We rely on Maven to (i) generate project templates, (ii) manage dependencies/classpath (iii) compile and package project artifacts. We do not need to understand the functionality of Maven comprehensively. We can start with the parts that are relevant to our given tasks and, of course, learn more about the tool as we go. NOTE: Again, you may have Maven installed already. If you do not want to duplicate Maven installation, then make sure that you do have the same version available and MAVEN_HOME is properly set. Otherwise, we will download Maven 3.3.9 and install it under $9322_PRAC$. Download Maven binary distribution Maven Download Page. Look for Maven 3.3.9 (current stable version). Choose either tar.gz or zip binary distributions to download. Extract the downloaded package (e.g., apache-maven-3.3.9-bin.tar.gz) to $9322_PRAC$. For the sake of illustration, you'd do: $ cd ~/cs9322-Prac $ tar -zxvf apache-maven-3.3.9-bin.tar.gz $ rm apache-maven-3.3.9-bin.tar.gz This will extract the contents to a new directory called apache-maven-3.3.9 and delete the downloaded file to save disk space. The all important directory here is apache-maven-3.3.9/bin and you want the directory to be in your PATH for convenient access. Now you want to setup: MAVEN_HOME environment variable (pointing to $9322_PRAC$/apache-maven-3.3.9, e.g., /Users/hpaik/cs9322-Prac/apache-maven-3.3.9) PATH to include the Maven bin directory (e.g., /Users/hpaik/cs9322-Prac/apache-maven-3.3.9/bin) Depending on your environment, how this is done would be different. In Mac OSX, for example, I'd edit my own ~/.profile and add: export MAVEN_HOME=/Users/hpaik/cs9322-Prac/apache-maven-3.3.9 export PATH="$PATH:/Users/hpaik/cs9322-Prac/apache-maven-3.3.9" You could do the same for your own path and variables. Now run Maven command to make sure that it is setup correctly. You can do this by: $ mvn --version You should see Maven reporting back the version of Maven and JDK. Integrating Maven with Eclipse We will use Maven both from a command line as well as Eclipse IDE. From Eclipse, we can access Maven through a plug-in. You can install the plug-in from Eclipse by the following steps: Open Eclipse IDE Click Help -> Install New Software... Click the Add button at top right corner At pop up, fill in: Name as "M2Eclipse" Location as "http://download.eclipse.org/technology/m2e/releases" In the following step, you should see something like this: Tick 'Maven Integration for Eclipse' and follow through with the installation process. Eventually, Eclipse may tell you that instead of fresh installation, it will do upgrade of the existing plug-ins. This is fine. After the installation, you may be asked to re-start Eclipse. Now we want the Maven plug-in to point to our own installation of Maven (rather than the internal/embedded one). Go to Preference -> Maven -> Installation. Click 'Add' button. Add the location of your Maven installation (i.e., your MAVEN_HOME). For illustration purpose, in the screenshot below, it shows it to be '/usr/dev/apache-maven-3.2.3'. Click OK. A Little Exercise with Maven To check that your Maven and Eclipse plug-in are setup, let us do a little 'HelloWorld' exercise. Open a terminal window, and 'cd' into Eclipse's workspace. This should be $9322_PRAC$/workspace. For example, in my machine, it is: '/Users/hpaik/cs9322-Prac/workspace'. Let's call this $YOUR_WORKSPACE$. Now under $YOUR_WORKSPACE$, type in the following (all in one line): $ mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false Don't be alarmed if this takes a while. Maven should be downloading necessary libraries to your local repository (normally located in a directory called '.m2' under your home). Eventually, you should see the 'BUILD SUCCESS' message. See the INFO lines ... it should tell you that a project is created under $YOUR_WORKSPACE$/my-app. This matches '-DartifactId' parameter (think of it as the name of your application/project). Open Eclipse. Go to File -> Import -> Maven -> Existing Maven Projects. Navigate to $YOUR_WORKSPACE$/my-app and click 'Finish' Open up 'my-app' project imported and briefly examine the files/structure generated by Maven (e.g., App.java). You should see something similar to this: Note pom.xml file. It is the configuration file for Maven. We will not do much with the file here, but from the following labs, you will be working with this file closely. As I said earlier, we will learn the elements of POM as we go. Now, do right click on the project name 'my-app' -> Run As -> maven install. By Maven convention, running 'mvn install' will prompt Maven to compile all Java files under src/main/java, include all dependent libraries in the classpath, package the classes into a 'jar' file and place it into /target directory, then finally install it in your local repository $your_home$/.m2 As a result, you will find my-app-1.0-SNAPSHOT.jar in the target directory. Now from a command line, go to $YOUR_WORKSPACE$/my-app Type in: java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App You should see 'Hello World!' in return. Part 3: Setting up a deployment environment In this section, we will describe how to setup the deployment environment using Docker. According to What-is-Docker, "Docker packages your application into a standardized unit for software development. Docker containers wrap a piece of software in a complete filesystem that contains everything needed to run: code, runtime, system tools, system libraries — anything that can be installed on a server. This guarantees that the software will always run the same, regardless of its environment." Again, we probably won't be able to learn and use everything there is on Docker within this course. We are mainly interested in using Docker as a deployment environment into which you copy, test your application, and make it available for others to run it. In your own time, we recommend you to find more information about Docker: Docker Overview here. Docker Tutorial (video) here Installing Docker Docker can be installed in two ways: (i) download Docker Platform (e.g., Docker for Mac, Docker for Windows), (ii) download what is named 'Docker Toolbox'. It does not matter which method you choose, however, there are minimum system requirements for the platform option. For example, you'd need Apple macOS Yosemite 10.10.3 or above to directly download and install Docker For Mac. To take a generic option, we use Docker Toolbox below. Throughout the labs in the course, we have tested the instructions for Docker Toolbox (v1.12.5). If you decide to use Docker for Windows or Mac, you might need to adjust some of the instructions yourself accordingly. Choose your option, and follow the instruction guide provided by Docker. Then, go to the next section of the lab for a brief exercise to test your installation. Option 1: Docker Toolbox (v1.12.5) Docker Toolbox is an installer which helps you to setup a Docker environment on your computer. You can find the Docker Toolbox installation guide here. Docker Toolbox Install (Windows) Docker Toolbox Install (OSX) After installing the package, run through the steps, and in the end, you should see something like the figues below. Note: choose 'Docker Quickstart Terminal' when promopted. Option 2: Docker Platforms If you are using the latest version of Windows or Mac operating systems you can use Docker for Windows or Mac. You can find the installation guide below. Docker for Windows Docker for Mac Brief exercise with Docker After installing the Docker Toolbox, we create a new virtual server using docker machine. This server is used to run the lab applications. Open Docker Quickstart Terminal. In the newly opened window run the follow command to create a new virtual machine $ docker-machine create --driver virtualbox comp9322srv Note: If running this command failed try again but before doing that use $docker-machine kill (or rm) commands to remove the faulty virtual machine first. If all goes well, you should see something like this with a message saying 'Docker is up and running'. To verify that the previous step was executed successfully, run the following command $ docker-machine ls The output should display a new server called "comp9322srv" in "Running" state. This server also should have a valid IP Address we can use to connect to from outside. Make note of the IP address for this server, as you will need it later. For example, mine below says: 192.168.99.101 So far, we have created a new virtual server which runs the docker containers. To connect to this server run the following command: $ docker-machine ssh comp9322srv If all goes well, now you are connected and logged into the server. Inside this server, in the next step, we will create a docker container which runs Apache Tomcat server. Many of our lab solutions and assignments run on a Tomcat server. Instead of setting up a container from scratch, we can use what is called a dockerfile (for more info here). A dockerfile contains all the instructions to build a docker image which Docker eventually uses to load into the conainer. The Docker community keeps ready-to-use dockerfiles with various configurations in Docker Hub. For example, if you have a quick look at the hub, you will find dockerfiles setup for common server environments such as Postgresql, mysql, node, etc. . The dockerfile for Apache Tomcat can be found here. But we can directly download and use the dockerfile via the following command. Run the following command to start a new Tomcat container in your server (i.e., comp9322srv) docker run --name tomcat8 -it --rm -p 8888:8080 tomcat:8.0 This command pulls the tomcat image from Docker Hub and runs it as a container. Importantly, it also maps port 8080 on the container to port 8888 on the comp9322srv (note '-p 8888:8080' option). The port 8888 is now available from outside. You can go to http://your-own-comp9322srv-ip:8888/ to access Tomcat homepage, where 'your-own-comp9322srv-ip' is the IP address you found for your server 'comp9322srv' in a previous step. For example, mine is "http://192.168.99.101:8888". When you access your own Tomcat, you will see something like this: At this stage you have successfully setup the deployment environment. A Tomcat container is running on comp9322srv server and you can deploy your applications to this container. In the next lab, we will discuss the instructions for deploying an application to Tomcat container. Please keep in mind comp9322srv server is the deployment server and it is a seprated from your development environment. Conclusion At the end of Lab00, see if you can tick the following boxes: I know where my Java 1.7 installation is, and JAVA_HOME is set. I have created the $9322_PRAC$ directory. I have Eclipse Luna running and I have configured it to work with JDK 1.7 I know where my Tomcat 8 installation is, CATALINA_BASE and CATALINA_HOME are set and I can start/shutdown the successfully. I know where my Maven installation is, and MAVEN_HOME, PATH are set. I can run mvn command from a command line. I have integrated Eclipse IDE and Maven with a plug-in. I have completed the little 'HelloWorld' exercise to verify it. I know how to setup docker toolbox I have created comp9322srv server to run docker containers I know how to run a new docker container which hosts Apache Tomcat https://docs.docker.com/docker-for-mac/docker-toolbox/
