$Id: RUNNING.txt,v 1.3 2004/09/22 13:31:18 cholmesny Exp $


               Running The GeoServer Binary Distribution
               =========================================

This release of GeoServer comes with a built-in Jetty servlet container, 
so that it can be run directly with out the need to download and configure
extra software.  GeoServer 1.3 fully implements the Web Feature Service (WFS)
specification, as well as a working implementation of the Web Map Service (WMS)
specification, both from the Open GIS Consortium (OGC).  In order to install
and run this application you must do the following:

(0) Download and Install a Java Development Kit

* Download a Java Development Kit (JDK) release (version 1.4 or later) from:

    http://java.sun.com/j2se/

* Install the JDK according to the instructions included with the release.

* Set an environment variable JAVA_HOME to the pathname of the directory
  into which you installed the JDK release.


(1) Download and Install the GeoServer 1.3 Binary Distribution

There is more help available at the <a href='http://docs.codehaus.org/display/GEOS/Home'>Geoserver WIKI</a> 

* Download a binary distribution of GeoServer from:

    http://sourceforge.net/projects/geoserver

  On a Windows platform, you will need:
    geoserver-1.3.*-binary.zip

  On a Unix platform, you will need:
    geoserver-1.3.*-binary.zip

* Unpack the binary distribution into a convenient location so that the
  distribution resides in its own directory (conventionally named
  "geoserver").  For the purposes of the remainder of this document,
  the symbolic name "${geoserver.home}" is used to refer to the full
  pathname of the release directory.


(2) Start Up GeoServer 1.3

There are two techniques by which GeoServer 1.3 can be started:

* Via an environment variable:
  - Set an environment variable GEOSERVER_HOME to the path of the directory
    into which you have installed GeoServer 1.3.
  - Execute the shell command:

      %GEOSERVER_HOME%\bin\startup             (Windows)

      $GEOSERVER_HOME/bin/startup.sh           (Unix)

* By modifying your current working directory:
  - Execute the following shell commands:

      cd %GEOSERVER_HOME%\bin                  (Windows)
      startup                                 (Windows)

      cd $GEOSERVER_HOME/bin                   (Unix)
      ./startup.sh                            (Unix)

After startup, the default web administration tool included with GeoServer 1.3 
will be available by browsing:

    http://localhost:8080/

Further information about configuring and running GeoServer 1.3 can be found in
the documentation included in the documentss directory, as well as on the 
GeoServer web site:

    http://geoserver.sourceforge.net


(3) Shut Down GeoServer 1.3

There are two techniques by which GeoServer 1.3 can be stopped:

* Via an environment variable:
  - Set an environment variable CATALINA_HOME to the path of the directory
    into which you have installed GeoServer 1.3.
  - Execute the shell command:

      %GEOSERVER_HOME%\bin\shutdown            (Windows)

      $GEOSERVER_HOME/bin/shutdown.sh          (Unix)

* By modifying your current working directory:
  - Execute the following shell commands:

      cd %GEOSERVER_HOME%\bin                  (Windows)
      shutdown                                (Windows)

      cd $GEOSERVER_HOME/bin                   (Unix)
      ./shutdown.sh                           (Unix)


(4) Troubleshooting:

There are only really 3 things that can go wrong during the stand-alone
GeoServer 1.3 install:

1) The most common hiccup is when another web server (or any process for that
   matter) has laid claim to port 8080.  This is the default HTTP port that
   GeoServer attempts to bind to at startup.  To change this, open the file:

       $GEOSERVER_HOME/documents/jetty.xml
    
   ...and search for '8080'.  Change it to a port that isn't in use, and is
   greater than 1024, as ports less than or equal to 1024 require superuser
   access to bind to.
   
   Restart GeoServer and you're in business.  Be sure that you replace the 
   "8080" in the URL you're using to access GeoServer.  For example, if you 
   change the port to 1977, you would request the URL 
   to http://localhost:1977/geoserver.

2) An "out of environment space" error when running the batch files in
   Win9X/ME-based operating systems.

   Right-click on the STARTUP.BAT and SHUTDOWN.BAT files.  Click on
   "Properties" then on the "Memory" tab.  For the "Initial environment" field,
   enter in something like 4096.
   
   After you click apply, Windows will create shortcuts in the directory with
   which you can use to start and stop the container.

3) The 'localhost' machine isn't found.  This could happen if you're behind a
   proxy.  If that's the case, make sure the proxy configuration for your
   browser knows that you shouldn't be going through the proxy to access the
   "localhost" machine.
   
   In Netscape, this is under Edit/preferences -> Advanced/proxies, and in
   Internet Explorer, Tools -> Internet Options -> Connections -> LAN Settings.