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