javaBootcampNoEclipse/docs/setup.org

11 KiB
Raw Permalink Blame History

Setup [Dude! Where's my Eclipse!?]

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.
  #!/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

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.