Home | History | Annotate | Download | only in doc
      1 OpenGrok deployment, step by step
      2 ---------------------------------
      3 
      4 One of the design goals of OpenGrok is that it should be easy to use, so a
      5 user should be able to use OpenGrok with a minimum of configuration. While the
      6 mimimum configuration is suitable for some users, it will not fit all users.
      7 The intent of this document is to offer a "step by step" guide for two
      8 different deployments of OpenGrok. A simple configuration suitable for small
      9 deployments, and a more "advanced" one for sites that want to host multiple
     10 source projects with a single OpenGrok server.
     11 
     12 Note that projects cannot have a "," in their name because of web application
     13 project field separator.
     14 
     15 Simple configuration.
     16 ---------------------
     17 
     18 The first thing you need to do is to create a directory structure to hold the
     19 sources and the database used by OpenGrok. I would suggest something like:
     20 
     21 /opengrok
     22 |-- bin
     23 |-- data
     24 `-- source
     25 
     26 You should copy the OpenGrok binaries into the bin-directory. The following
     27 command should do the trick:
     28 
     29 $ cp -r OpenGrok opengrok.jar lib /opengrok/bin
     30 
     31 Edit OpenGrok, review the configuration section and set at least the
     32 following parameters to reflect your system and requirements:
     33 SRC_ROOT=/opengrok/source
     34 DATA_ROOT=/opengrok/data
     35 EXUB_CTAGS=/absolute/path/to/Exubrant/Ctags
     36 
     37 The last thing we need to do is to configure the web application. To do so, 
     38 please execute the following commands:
     39 $ mkdir /opengrok/web/source
     40 $ cd /opengrok/web/source
     41 $ unzip /path/to/opengrok-release/source.war
     42 
     43 edit WEB-INF/web.xml and specify SRC_ROOT and DATA_ROOT.
     44 
     45 You may also want to modify the file index_body.html before you re-create
     46 the war-file with the following commands:
     47 
     48 $ cd /opengrok/web/source
     49 $ zip -r /opengrok/web/source.war
     50 
     51 Deploy OpenGrok to a Tomcat server by copying source.war to the "webapps"
     52 directory in the Tomcat installation.
     53 In case you have Glassfish, you can use web admin UI to deploy the war, or
     54 you can simply put it in your domains directory in the "autodeploy" folder.
     55 If you are using any other web application container servers, please refer to
     56 their documentation on war deployments.
     57 
     58 
     59 Advanced configuration.
     60 -----------------------
     61 
     62 This configuration is suitable for deployments where you would like to host
     63 multiple source projects in the same OpenGrok installation. This configuration
     64 is also suitable if you want to run the index generation on one server, and
     65 the web interface on another server.
     66 
     67 I would recommend that you create a unique user and group named opengrok to
     68 own the files and run the indexing software.
     69 
     70 As with the simple configuration you need to set up a directory structure.
     71 I would suggest something like:
     72 
     73 /opengrok
     74 |-- bin
     75 |-- smf
     76 |-- stage1
     77 |   |-- data
     78 |   `-- source
     79 `-- stage2
     80     |-- data
     81     `-- source
     82 
     83 The reason we need two stage directories is that the web service will use one
     84 while we're updating the other.
     85 
     86 You should then populate the directory with files from the OpenGrok 
     87 distribution:
     88 $ cp -r opengrok.jar lib /opengrok/bin
     89 $ cp -r tools/smf /opengrok
     90 
     91 (Please note that you should use the same value for SRC_ROOT and DATA_ROOT for
     92 on all servers if you generate indexes on one server and run the web interface
     93 on another server. On Solaris you could use the automounter to mount /opengrok
     94 on all servers, or you could specify the path by using /net/servername/opengrok)
     95 
     96 The /opengrok/smf subdirectory contains scripts and manifest files that may be
     97 used to run the index generation as a Solaris service. You will find a script
     98 that may be used as a skeleton to create you own startup / shutdown script in
     99 tools/init.d. This should be placed in /etc/init.d and appropriate links
    100 must be creted from the desired rcX.d directory.
    101 
    102 Solaris users should edit /opengrok/smf/opengrok.xml and verify that the
    103 variables specified there are correct. The service is imported by executing
    104 the following command:
    105 # svccfg import /opengrok/smf/opengrok.xml
    106 
    107 For other platforms these variables are specified in /etc/init.d/opengrok.sh
    108 
    109 The next thing to do is to populate the source trees with the sources you want
    110 OpenGrok to serve. E.g. to create your own "mirror" of the OpenGrok sources you
    111 would execute:
    112 
    113 $ cd /opengrok/stage1/source
    114 $ hg clone ssh://anon (a] opensolaris.org/hg/opengrok/trunk opengrok
    115 $ cp -pr opengrok /opengrok/stage2/source
    116 
    117 If you are going to host source from multiple projects in your OpenGrok server,
    118 you should edit /opengrok/smf/indexer.sh and look for the line:
    119       # ADD_PROJECTS="-P -p /onnv-gate -W ${DATA_ROOT}/../configuration.xml"
    120 
    121 Remove the '#' to activate the line, and replace "/onnv-gate" with the 
    122 directory name of the project you would like to be selected as default (to 
    123 select the opengrok source we added above, insert "/opengrok").
    124 
    125 The last step we need to do before we can start generating the indices is to
    126 create the configuration file used by the web interface. You create the
    127 configuration file by executing the following command:
    128 
    129 $ java -jar /opengrok/bin/opengrok.jar -W /opengrok/stage1/configuration.xml \
    130        -c /path/to/ctags -P -S -v -s /opengrok/stage1/source \
    131        -d /opengrok/stage1/data
    132 
    133 You can now start generating indices by executing:
    134 Solaris with SMF:
    135 # svcadm enable opengrok
    136 Or if you use scripts in /etc/init.d:
    137 # /etc/init.d/opengrok start
    138 
    139 The last thing we need to do is to configure the web application. To do so, 
    140 please execute the following commands:
    141 $ mkdir /opengrok/web/source
    142 $ cd /opengrok/web/source
    143 $ unzip /path/to/opengrok-release/source.war
    144 
    145 edit WEB-INF/web.xml and add the following section (next to all the other
    146 <context-param> entries):
    147 
    148  <context-param>
    149    <param-name>CONFIGURATION</param-name>
    150    <param-value>/opengrok/configuration.xml</param-value>
    151  </context-param>
    152 
    153  <context-param>
    154    <param-name>ConfigAddress</param-name>
    155    <param-value>localhost:2424</param-value>
    156  </context-param>
    157 
    158 The last entry will let the web application listen on port 2424 for
    159 configuration updates. There is currently _no_ authentication implemented here,
    160 so you should not add an ip address reachable from an untrusted source.
    161 If you run the index generation on another server than the web server, you must
    162 add one of the external interfaces of the web server (but it should _NOT_ be
    163 reachable from external hosts).
    164 
    165 You may also want to modify the file index_body.html before you re-create
    166 the jar-file with the following commands:
    167 
    168 $ cd /opengrok/web/source
    169 $ zip -r /opengrok/web/source.war
    170 
    171 Deploy OpenGrok to a Tomcat server by copying source.war to the webapps
    172 directory in the Tomcat installation.
    173 In case you have Glassfish, you can use web admin UI to deploy the war, or
    174 you can simply put it in your domains directory in the "autodeploy" folder.
    175 If you are using any other web application container servers, please refer to
    176 their documentation on war deployments.
    177 
    178 
    179