diff --git a/docs/setup.org b/docs/setup.org new file mode 100644 index 0000000..e047944 --- /dev/null +++ b/docs/setup.org @@ -0,0 +1,253 @@ + +#+TITLE: Setup [Dude! Where's my Eclipse!?] +#+DATE: [2017-08-15 Tue] +#+AUTHOR: Éibhear Ó hAnluain, Version 1 +#+EMAIL: eibhear.ohanluain@version1.com +#+OPTIONS: ':nil *:t -:t ::t <:t H:3 \n:nil ^:{} arch:headline +#+OPTIONS: author:t c:nil creator:comment d:(not "LOGBOOK") date:t +#+OPTIONS: e:t email:nil f:t inline:t num:t p:nil pri:nil stat:t +#+OPTIONS: tags:t tasks:t tex:t timestamp:t toc:t todo:t |:t +#+CREATOR: +#+DESCRIPTION: How to set up an environment to facilitate the preparation and presentation of the "Dude! Where's my Eclipse!?" java bootcamp module. +#+EXCLUDE_TAGS: noexport +#+KEYWORDS: +#+LANGUAGE: en +#+SELECT_TAGS: export + +* Setup [Dude! Where's my Eclipse] + +** Introduction + + This document outlines how to prepare an environment that you can + use to work on or give the presentation made available at + https://gitlab.com/eibhear/javaBootcampNoEclipse/. + + If you are unable to follow these instructions precisely, you could + contact the author. + +*** Assumptions + 1. You can easily create and destroy a basic Linux VM, such as is + possible with an account on Amazon's AWS or Microsoft's Azure. + 2. If the specific versions of packages or OS's mentioned below + are not available to you, you are able to get and use + appropriate alternatives. + +*** Software + The following OS and package versions were used in the preparation + and presentation of this module: + - Debian Linux 9.1 (installed using the image file + =debian-9.1.0-amd64-netinst.iso=, as downloaded + https://cdimage.debian.org/) + - Tomcat 8 (including the Tomcat 8 Manager (=tomcat8-admin=)) + - OpenJDK-8 JDK + - =git= (any version) needed to interact with the + code/presentation. + + All other tools and utilities mentioned in this document were + installed to support the preparation and presentation of the + module. For each one, you may decide to use an alternative package + or take a different approach. + + - =aptitude= :: The author prefers this to =apt-get=. + - =sudo= :: To allow for administration actions on the VM. + - =openssh-server= :: To facilitate inbound connections to the + command-line. + - =curl=, =wget=, =links= :: Useful, text-based, web client tools. + - =emacs-nox=, =magit= :: Development tools. GNU/Emacs to edit + files, =magit= to interact with the git repository through + =emacs=. + +*** Other Notes + - The package =tomcat8-docs= was /not/ installed as it seemed to + break tomcat in a way that the author hadn't time to investigate + and fix. + - The author wanted to use the command-line to deploy the + application into the tomcat instance, but, again, all attempts + broke tomcat in a way that was going to be costly to investigate + and fix, so therefore we conceded the =manager-gui= for this. + + If you are aware of this behaviour in tomcat, you might contact + the author with information on what may have been the problem(s). + +** Setup + +*** OS + The VM was built as a Debian GNU/Linux server, release 9.1 + (/Jessie/). The only note-worthy comment on the installation is + that when asked for what software to install, none was selected + (i.e. the default options were de-selected -- debian installs + mandatory packages to give you a working server; when you're asked + to select software to install, these are to be /additional/ + packages). This resulted in a base, headless system, which was + then configured according to the script below. + +*** Configuration + The following shell script was executed by the user =root= once + the VM build was completed to configure the environment for this + presentation. Prior to running this script, you will need to make + the following edits to the script: + - Replace the two instances of =%%normal_user%%= with the username + of the user you provided during the installation. This will + allow that user to perform admin actions. + - Replace =%%tomcat_manager_password%%= with a password to be used + with the username =tomcat= to access the =/manager= application. + #+BEGIN_SRC sh + #!/bin/bash + + # Needed to use aptitude + echo "apt-get install -y aptitude" + apt-get install -y aptitude + + # Needed to give the normal admin access. + echo "aptitude install -y sudo " + aptitude install -y sudo + + # Needed for basic inbound connectivity + echo "aptitude install -y openssh-server" + aptitude install -y openssh-server + + # Needed for local and outbound connectivity testing + echo "aptitude install -y curl wget links" + aptitude install -y curl wget links + + # Needed for simple development activity + echo "aptitude install -y git emacs-nox magit openjdk-8-jdk" + aptitude install -y git emacs-nox magit openjdk-8-jdk + + # needed to test with tomcat + echo "aptitude install -y tomcat8 tomcat8-admin" + aptitude install -y tomcat8 tomcat8-admin + + # Allow the user to perform admin actions. + echo "usermod -a -G sudo %%normal_user%%" + usermod -a -G sudo %%normal_user%% + + # This allows access to the tomcat manager module. See + # http://tomcat.apache.org/tomcat-8.0-doc/manager-howto.html + # for further information. + echo "Building /var/lib/tomcat8/conf/tomcat-users.xml" + cat << EOF > /var/lib/tomcat8/conf/tomcat-users.xml + + + + + + + + + + EOF + + # Needed to allow access to the tomcat manager module from outside the + # local VM (so that you can connect from a different PC/server). + echo "Building /usr/share/tomcat8-admin/manager/META-INF/context.xml" + cat << EOF > /usr/share/tomcat8-admin/manager/META-INF/context.xml + + + + + + EOF + + # Restarting tomcat, to be sure, to be sure. + echo "service tomcat8 restart" + service tomcat8 restart + + #+END_SRC + +*** Testing + To ensure all is set up correctly... + 1) Review the output of the script above to see if there are any + errors. + 2) You should be able to connect to your VM using =ssh= as your + configured user: + : ssh @ + 3) You should be able to run the =sudo= command to perform admin + activities. For example, the following command will present + your VM's nework routing table. You should be logged in as your + "normal user" and you will be required to provide its password + (i.e. /not/ root's password). + : sudo route + 4) You should be able to access the following URLs from within + your VM (shown here as calls to the =links= utility): + - tomcat + : links http://localhost:8080/ + - tomcat manager + : links http://localhost:8080/manager/html + 5) You should be able to access these same URLs from a remote + location (e.g. your desktop PC). + + If this doesn't work, it may not be related to your VM + configuration, but to the network access controls between the + remote location and your VM. For example, if there is a + firewall between the two machines, you'll have to get past it. + 6) Test the module itself (these commands assume you are logged + onto the VM as a normal user): + : mkdir -pv ${HOME}/development + : cd ${HOME}/development + : git clone https://gitlab.com/eibhear/javaBootcampNoEclipse.git + : cd ${HOME}/development/javaBootcampNoEclipse + : git checkout all-lessons-in-one-shell-script + : ${HOME}/development/javaBootcampNoEclipse/source/scripts/allInOne.sh + If all is well, there will be two new files in + =.../source/lib/=, =javaBootcampNoEclipse-up-to-lesson-4.war= + and =javaBootcampNoEclipse-lesson-5.war=. Deploy one or both of + these war files to tomcat using + =http://:8080/manager/html= to test them they + should both work without issue. + + If all is well, you're in a position to work with the code + provided in the module or even to present it. diff --git a/docs/setup.pdf b/docs/setup.pdf new file mode 100644 index 0000000..f888a7a Binary files /dev/null and b/docs/setup.pdf differ