rkirkpat.net EasyScout 2.0 
SETUP (2004/01/01)
==========================

Requirements: 
  The software may operate with lesser (and most probably with later) versions
  than listed below, but I have not tested it as such.

  *) Debian GNU/Linux 3.0 (or equivalent)
  *) Tomcat 4.0.3
  *) Apache 1.3.26 (with SSL and Jakarta-Tomcat support)
  *) Java 1.3.1 (both JVM and SDK)
  *) Python 2.1.3

  Debian 3.0 is the recommended operating system on which to run EasyScout, due
  to its flexibility, security, stability, and because it is completely free. :)
  Tomcat and Apache are included with Debian in the tomcat4, apache-ssl, and
  libapache-mod-jk packages. Java packages can be downloaded from
  http://www.blackdown.org/, or by adding the following to
  /etc/apt/sources.list, and then installing the j2re1.3 and j2sdk1.3 packages.

  deb ftp://ibiblio.org/pub/linux/devel/lang/java/blackdown.org/debian woody main non-free

  The hardware requirements for EasyScout are pretty light. At minimum a Pentium
  2 class machine with 128MB of RAM and 1GB of disk space (for both operating
  system and EasyScout) is needed to host a single troop. I am currently hosting
  a installation for my scout troop on a P2-400MHz w/256MB RAM and 15GB RAID1
  disk, and it quite fast. As for Internet connection, a permanent one is need,
  such as DSL or T1 service. Cable connections would probably work, but few cable
  ISPs allow servers to be run on connected machines. For my installation, I am
  hosting over a 144kbit IDSL line without issues.

  Of course, as the number of troops hosted on a server increase, additional
  resources will be required. I recommend to do load testing of your server
  before deploying it to verify it can stand up to the expected load.

Installation:

  1) Place the package directory (i.e. the result of unpacking the tar-ball this
     file is found in) on the server that will be hosting EasyScout. The exact
     location does not matter, but /home/apache/easyscout is one possibility.

  2) The ownership of this directory should be assigned to the user in charge of
     maintaining the installation. The group ownership though needs to be
     assigned to a group that both the user Tomcat is running as and this user
     in charge of maintenance are members of. The file and directory permissions
     should be such that user and group have read/write access, and others have
     no access. I.e.

# echo "escout:x:10000:rkirkpat,tomcat4" >> /etc/group
# cd /home/apache/
# chown -R rkirkpat.escout easyscout
# find easyscout -type f -exec chmod a-rwx,ug+rw {} \;
# find easyscout -type d -exec chmod a-rwx,ug+rwx,g+s {} \;

  3) Symbolically link this directory location to
     /var/lib/tomcat4/webapps/easyscout. I.e.

# cd /var/lib/tomcat4/webapps/
# ln -s /home/apache/easyscout easyscout

  4) Compile the Java class files into byte code to be executed by Tomcat. This
     can be done by first setting up the CLASSPATH variable, and then using the
     Java SDK utilities to compile the classes. The final command will generate
     some warning you can safely ignore, providing you are using Java 1.3.

# cd /var/lib/tomcat4/webapps/easyscout/WEB-INF/classes/
# for jar in /usr/share/java/*.jar ; do CLASSPATH=${CLASSPATH}:$jar; done
# export CLASSPATH=$CLASSPATH:/var/lib/tomcat4/webapps/easyscout/WEB-INF/classes/
# javac ES.java

  5) Configure the EasyScout installation by editing the
     WEB-INF/classes/cx/warp/scout/lookup/properties.xml file. The important
     tags:
     
     a) WebRoot :: Where the root of the package directory is found.
     b) AppRoot :: The path to this directory as served by the web server.
     c) Images  :: Relative web path to the images.
     d) Servlet :: Relative web path to the main Java servlet, ES.class.
     e) Data    :: Where the data directory for troop information is located.
     f) Admin   :: Email address for the EasyScout admin. This needs to be
                   specified.
     h) Home    :: The home page associated with EasyScout. This also needs to
                   specified.
     i) Sessions:: Unused.

  6) The information for each troop is saved in a separate data file. The format
     for this file is serialized Java objects (in other words, binary and quite
     opaque). Furthermore, this file is gzipped compressed, and DES
     encrypted. The DES key is stored in the first line of des.key file found in
     the data directory. It is best to generate this key from random data. I.e.

# cd /var/lib/tomcat4/webapps/easyscout/WEB-INF/data/
# python <<EOF
random = open("/dev/random","rb")
key = ""
while len(key) != 512:
  byte = random.read(1)
  if ord(byte) >= 0x20 and ord(byte) <= 0x7e: key += byte
open("des.key","wb").write(key)
EOF

   7) There is a special troop named 'root' that actually provides access to a
      list of all troops registered with the EasyScout installation. From this
      list, any of the troops can be accessed with full read/write access
      and without passwords. Consider this the admin or superuser account. The
      password for 'root' is taken from the second line of the des.key file
      created above. I.e.

# cd /var/lib/tomcat4/webapps/easyscout/WEB-INF/data/
# echo "SuperSecretPassword" >> des.key

   8) At this point, the EasyScout WebApp directory is configured and ready to
      go. Re-apply the user and group ownership and permissions mentioned above
      to make sure everything is in good shape.

   9) Configuring Apache: It is highly recommended that EasyScout only be
      accessible via HTTPS (web over SSL), as is used by many online
      stores. This encrypts the data exchanged between the client and server,
      including passwords. See the Apache SSL documentation for details on
      setting the web server itself up.

      a) Configure support for the Apache/Tomcat interface by adding the
         following to the /etc/apache-ssl/httpd.conf file:

# The module with Tomcat support.
LoadModule jk_module /usr/lib/apache/1.3/mod_jk.so

# Configure the module.
JkWorkersFile /etc/tomcat/jk/workers.properties
JkLogFile /var/log/tomcat4/mod_jk.log
JkLogLevel info

       b) Then in the definition for the (virtual) server hosting EasyScout, add
          the following line. This maps Apache web paths to Tomcat web
          paths. I.e. for the below, the URL
          http://{hostname}/easyscout/servlet/ES would be mapped to the Tomcat
          WebApp 'easyscout', and cause the WEB-INF/classes/ES.class file to be
          executed.

JkMount /easyscout/* ajp13

  10) Configuring Tomcat:

      a) To allow EasyScout read/write access to the data directory, add the
         following to the end of the /etc/tomcat4/policy.d/04weapps.policy file. 

// Allow read/write of easyscout data files.
grant codeBase "file:${catalina.home}/webapps/easyscout/-" {
    permission java.io.FilePermission "/var/lib/tomcat4/webapps/easyscout/WEB-INF/data/-", "write";
};

      b) To disable the Tomcat builtin web server and therefore only access
         Tomcat Java servlets via Apache, edit the /etc/tomcat4/server.xml
         file. Make sure that the HttpConnector definition for port 8180 is
         commented out, while the AJP13Connector on port 8009 is NOT
         commented out. Make sure that the 'address' parameter of the
         AJP13Connector is set to '127.0.0.1' so only the local Apache server
         can connect. A bare-bones configuration would look something like this:

<Server port="8005" shutdown="SHUTDOWN" debug="0">
  <Service name="Tomcat-Standalone">
    <Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
               port="8009" minProcessors="5" maxProcessors="75"
               acceptCount="10" debug="0" address="127.0.0.1"/>
    <Engine name="Standalone" defaultHost="localhost" debug="0">
      <Logger className="org.apache.catalina.logger.FileLogger"
              prefix="catalina_log." suffix=".txt"
              timestamp="true"/>
      <Realm className="org.apache.catalina.realm.MemoryRealm" />
      <Host name="localhost" debug="0" appBase="webapps" unpackWARs="false">
        <Valve className="org.apache.catalina.valves.AccessLogValve"
                 directory="logs"  prefix="localhost_access_log." suffix=".txt"
                 pattern="common" />
        <Logger className="org.apache.catalina.logger.FileLogger"
                 directory="logs"  prefix="localhost_log." suffix=".txt"
	        timestamp="true"/>
        <Context path="/manager" docBase="manager"
	         debug="0" privileged="true"/>
      </Host>
    </Engine>
  </Service>
</Server>

  11) Finally, fire up Tomcat and Apache, then point a web browser at your
      server, with the URL 'http://{hostname}/easyscout/servlet/ES'. You should
      be rewarded with the login screen. See 'http://{hostname}/easyscout/' for
      HTML fragments for hooking into EasyScout login and troop creation forms.

Notes:

The DES key stored in des.key (and the root account password for that matter)
should be protected from prying eyes. As setup above, any member of the escout
group has the ability to read this file. 

Also note that if the DES key is changed at any time, all existing data files
will be unreadable. This means if you lose the DES key, the data files are
worthless. The moral here is to create backups (export XML files) on a regular
basis from the EasyScout web interface. See the associated ESPyUtils package for
help in automating this, as well for help in restoring backups.

If you have not already noticed, these setup instructions are heavily Debian
centric, mainly because that is what I use for all of my servers. If you are
using a different Linux distribution, you will have to extrapolate from these
setup instructions to the specifics required for your installation.

If there is anything missing or unclear above, or you still have questions,
please feel free to contact me (scouts@rkirkpat.net) and I will do my best to
help you out.

---------------------------------------------------------------------------
|   "For to me to live is Christ, and to die is gain."                    |
|                                            --- Philippians 1:21 (KJV)   |
---------------------------------------------------------------------------
|   Ryan Kirkpatrick  |  Boulder, Colorado  |  http://www.rkirkpat.net/   |
---------------------------------------------------------------------------

