#+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.