Set up document

This commit is contained in:
Éibhear Ó hAnluain 2017-08-15 11:03:26 +01:00
parent dbf971331e
commit 42608808a9
2 changed files with 253 additions and 0 deletions

253
docs/setup.org Normal file
View file

@ -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.

BIN
docs/setup.pdf Normal file

Binary file not shown.