xref: /opengrok/trunk/doc/EXAMPLE.txt

OpenGrok deployment, step by step
---------------------------------

One of the design goals of OpenGrok is that it should be easy to use, so a
user should be able to use OpenGrok with a minimum of configuration. While the
mimimum configuration is suitable for some users, it will not fit all users.
The intent of this document is to offer a "step by step" guide for two
different deployments of OpenGrok. A simple configuration suitable for small
deployments, and a more "advanced" one for sites that want to host multiple
source projects with a single OpenGrok server.

Note that projects cannot have a "," in their name because of web application
project field separator.

Simple configuration.
---------------------

The first thing you need to do is to create a directory structure to hold the
sources and the database used by OpenGrok. I would suggest something like:

/opengrok
|-- bin
|-- data
`-- source

You should copy the OpenGrok binaries into the bin-directory. The following
command should do the trick:

$ cp -r OpenGrok opengrok.jar lib /opengrok/bin

Edit OpenGrok, review the configuration section and set at least the
following parameters to reflect your system and requirements:
SRC_ROOT=/opengrok/source
DATA_ROOT=/opengrok/data
EXUB_CTAGS=/absolute/path/to/Exubrant/Ctags

The last thing we need to do is to configure the web application. To do so, 
please execute the following commands:
$ mkdir /opengrok/web/source
$ cd /opengrok/web/source
$ unzip /path/to/opengrok-release/source.war

edit WEB-INF/web.xml and specify SRC_ROOT and DATA_ROOT.

You may also want to modify the file index_body.html before you re-create
the war-file with the following commands:

$ cd /opengrok/web/source
$ zip -r /opengrok/web/source.war

Deploy OpenGrok to a Tomcat server by copying source.war to the "webapps"
directory in the Tomcat installation.
In case you have Glassfish, you can use web admin UI to deploy the war, or
you can simply put it in your domains directory in the "autodeploy" folder.
If you are using any other web application container servers, please refer to
their documentation on war deployments.


Advanced configuration.
-----------------------

This configuration is suitable for deployments where you would like to host
multiple source projects in the same OpenGrok installation. This configuration
is also suitable if you want to run the index generation on one server, and
the web interface on another server.

I would recommend that you create a unique user and group named opengrok to
own the files and run the indexing software.

As with the simple configuration you need to set up a directory structure.
I would suggest something like:

/opengrok
|-- bin
|-- smf
|-- stage1
|   |-- data
|   `-- source
`-- stage2
    |-- data
    `-- source

The reason we need two stage directories is that the web service will use one
while we're updating the other.

You should then populate the directory with files from the OpenGrok 
distribution:
$ cp -r opengrok.jar lib /opengrok/bin
$ cp -r tools/smf /opengrok

(Please note that you should use the same value for SRC_ROOT and DATA_ROOT for
on all servers if you generate indexes on one server and run the web interface
on another server. On Solaris you could use the automounter to mount /opengrok
on all servers, or you could specify the path by using /net/servername/opengrok)

The /opengrok/smf subdirectory contains scripts and manifest files that may be
used to run the index generation as a Solaris service. You will find a script
that may be used as a skeleton to create you own startup / shutdown script in
tools/init.d. This should be placed in /etc/init.d and appropriate links
must be creted from the desired rcX.d directory.

Solaris users should edit /opengrok/smf/opengrok.xml and verify that the
variables specified there are correct. The service is imported by executing
the following command:
# svccfg import /opengrok/smf/opengrok.xml

For other platforms these variables are specified in /etc/init.d/opengrok.sh

The next thing to do is to populate the source trees with the sources you want
OpenGrok to serve. E.g. to create your own "mirror" of the OpenGrok sources you
would execute:

$ cd /opengrok/stage1/source
$ hg clone ssh://anon (a] opensolaris.org/hg/opengrok/trunk opengrok
$ cp -pr opengrok /opengrok/stage2/source

If you are going to host source from multiple projects in your OpenGrok server,
you should edit /opengrok/smf/indexer.sh and look for the line:
      # ADD_PROJECTS="-P -p /onnv-gate -W ${DATA_ROOT}/../configuration.xml"

Remove the '#' to activate the line, and replace "/onnv-gate" with the 
directory name of the project you would like to be selected as default (to 
select the opengrok source we added above, insert "/opengrok").

The last step we need to do before we can start generating the indices is to
create the configuration file used by the web interface. You create the
configuration file by executing the following command:

$ java -jar /opengrok/bin/opengrok.jar -W /opengrok/stage1/configuration.xml \
       -c /path/to/ctags -P -S -v -s /opengrok/stage1/source \
       -d /opengrok/stage1/data

You can now start generating indices by executing:
Solaris with SMF:
# svcadm enable opengrok
Or if you use scripts in /etc/init.d:
# /etc/init.d/opengrok start

The last thing we need to do is to configure the web application. To do so, 
please execute the following commands:
$ mkdir /opengrok/web/source
$ cd /opengrok/web/source
$ unzip /path/to/opengrok-release/source.war

edit WEB-INF/web.xml and add the following section (next to all the other
<context-param> entries):

 <context-param>
   <param-name>CONFIGURATION</param-name>
   <param-value>/opengrok/configuration.xml</param-value>
 </context-param>

 <context-param>
   <param-name>ConfigAddress</param-name>
   <param-value>localhost:2424</param-value>
 </context-param>

The last entry will let the web application listen on port 2424 for
configuration updates. There is currently _no_ authentication implemented here,
so you should not add an ip address reachable from an untrusted source.
If you run the index generation on another server than the web server, you must
add one of the external interfaces of the web server (but it should _NOT_ be
reachable from external hosts).

You may also want to modify the file index_body.html before you re-create
the jar-file with the following commands:

$ cd /opengrok/web/source
$ zip -r /opengrok/web/source.war

Deploy OpenGrok to a Tomcat server by copying source.war to the webapps
directory in the Tomcat installation.
In case you have Glassfish, you can use web admin UI to deploy the war, or
you can simply put it in your domains directory in the "autodeploy" folder.
If you are using any other web application container servers, please refer to
their documentation on war deployments.