Set up document

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
+      <?xml version="1.0" encoding="UTF-8"?>
+      <!--
+        Licensed to the Apache Software Foundation (ASF) under one or more
+        contributor license agreements.  See the NOTICE file distributed with
+        this work for additional information regarding copyright ownership.
+        The ASF licenses this file to You under the Apache License, Version 2.0
+        (the "License"); you may not use this file except in compliance with
+        the License.  You may obtain a copy of the License at
+
+            http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+      -->
+      <tomcat-users xmlns="http://tomcat.apache.org/xml"
+                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                    xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
+                    version="1.0">
+      <!--
+        NOTE:  By default, no user is included in the "manager-gui" role required
+        to operate the "/manager/html" web application.  If you wish to use this app,
+        you must define such a user - the username and password are arbitrary. It is
+        strongly recommended that you do NOT use one of the users in the commented out
+        section below since they are intended for use with the examples web
+        application.
+      -->
+      <!--
+        NOTE:  The sample user and role entries below are intended for use with the
+        examples web application. They are wrapped in a comment and thus are ignored
+        when reading this file. If you wish to configure these users for use with the
+        examples web application, do not forget to remove the <!.. ..> that surrounds
+        them. You will also need to set the passwords to something appropriate.
+      -->
+        <role rolename="manager-gui"/>
+        <user username="tomcat" password="%%tomcat_manager_password%%" roles="manager-gui"/>
+      <!--
+        <role rolename="tomcat"/>
+        <role rolename="role1"/>
+        <user username="tomcat" password="<must-be-changed>" roles="tomcat"/>
+        <user username="both" password="<must-be-changed>" roles="tomcat,role1"/>
+        <user username="role1" password="<must-be-changed>" roles="role1"/>
+      -->
+      </tomcat-users>
+      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
+      <?xml version="1.0" encoding="UTF-8"?>
+      <!--
+        Licensed to the Apache Software Foundation (ASF) under one or more
+        contributor license agreements.  See the NOTICE file distributed with
+        this work for additional information regarding copyright ownership.
+        The ASF licenses this file to You under the Apache License, Version 2.0
+        (the "License"); you may not use this file except in compliance with
+        the License.  You may obtain a copy of the License at
+
+            http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+      -->
+      <Context antiResourceLocking="false" privileged="true" >
+        <Valve className="org.apache.catalina.valves.RemoteAddrValve"
+               allow=".*" />
+      </Context>
+      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 <username>@<vmNameOrIP>
+    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://<vmNameOrIP>: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.