Wiki code for How to install OpenGrok

Hide Line numbers
1: = How to install & use [[image:Project opengrok.WebHome@logo.png||alt="OpenGrok"]] =
2: 
3: {OpenGrok can be installed and used under different use cases, we will just show how to use the wrapper script. Advanced usage depends on your knowledge of running java applications and command line options of {OpenGrok.
4:  Note, that you **need** the **index setup** no matter what use case you plan to use. Without indexes {Opengrok will be simply useless.
5:  This document is a live document, we are updating it as the new versions/changes come out (note the date at the right bottom of the page).
6: 
7: === Requirements ===
8: 
9: You need the following:
10: 
11: * [[JDK>>http://java.sun.com/javase/downloads/index.jsp]] 1.6 or higher
12: * {OpenGrok **binaries** from [[files section>>Project opengrok.files]](either the package for Solaris, or .tar.gz with binaries, NOT the src! )
13: * [[Exuberant Ctags>>http://ctags.sourceforge.net]] for analysis
14: * A servlet container like [[GlassFish>>https://glassfish.dev.java.net/]] or [[Tomcat>>http://tomcat.apache.org]] (5.x or later)
15: * If history is needed, appropriate binary (& repository in cvs/cvn case) must be present on the system (e.g. [[Subversion>>http://subversion.tigris.org]] or [[Mercurial>>http://www.selenic.com/mercurial/wiki/index.cgi]] or [[SCCS>>http://dlc.sun.com/osol/devpro/downloads/current/]] or ... )
16: 
17: === Recommended links to read for advanced users ===
18: 
19: * [[Sample setup of opengrok>>http://src.opensolaris.org/source/xref/opengrok/trunk/doc/EXAMPLE.txt]]
20: * [[Sample run script for creation of indexes(no projects).>>http://src.opensolaris.org/source/xref/opengrok/trunk/run.sh]]
21: * [[development trunk usage info(CommandLineOptions class)>>http://src.opensolaris.org/source/xref/opengrok/trunk/src/org/opensolaris/opengrok/index/CommandLineOptions.java#69]]
22: 
23: == INDEX and web application setup ==
24: 
25: After installing the package (e.g. {{code}}pkgadd -d ./OSOLopengrok-0.?.pkg{{/code}}) or untgzing the binaries in your target directory (e.g. {{code}}cd your_target_dir ; gzcat opengrok-0.?.tar.gz | tar xf - {{/code}}), you just need to create the index and then you can use the command line interface to grok our sources.
26: 
27: === Creating the index ===
28: 
29:  OpenGrok’s command line use is a typical case where OpenGrok is deployed as indexing service on a webserver for an active source repository, which is updated automatically using scheduled cron jobs.
30: **Project concept** - one project is one directory underneath SRC_ROOT and usually contains a checkout of a project(or it’s branch, version, ...) sources, it can have several attributes (in its XML description), note that interface of projects is being stabilized so it can change. Projects effectively replace need for more web applications with opengrok .war and leave you with one indexer and one web application serving MORE source code repositories - projects. A nice concept is to have directories underneath SRC_ROOT with a naming convention, thereby creating a good overview of projects (e.g. name-version-branch). Then you have a simple update script & simple index refresher script in place, which simplifies management of more repositories.
31:  [[image:setup-project.png]]
32: 
33: ==== Step.0 - Setting up the Sources. Having the web application container ready. ====
34: 
35: Source base must be available locally for OpenGrok to work efficiently. No changes are required to your source tree. If the code is under CVS or SVN, OpenGrok requires the **checked out source** tree under SRC_ROOT.
36: **Note:** A local CVSROOT (or SVN if opengrok version less than 0.7) repository must be available. File history will not be fetched from a remote server for CVS (& SVN if opengrok version less than 0.7) !. For newer opengrok versions you must use option {{code}}-r on{{/code}} must be used for remote repositories history to be indexed, also note this can be more time demanding.
37: Note also that OpenGrok ignores symbolic links.
38: 
39: Please install web application container of your choice (e.g. [[Tomcat>>http://tomcat.apache.org/]],[[GlassFish>>https://glassfish.dev.java.net/]] or [[Sun Java Application Server>>http://www.sun.com/software/products/appsrvr]]) before going to the next step and make sure it’s started.
40: 
41: ==== Step.1 - Deploy the web application ====
42: 
43: We provided you with OpenGrok wrapper script, which should aid in deploying the web application.
44: Please change to opengrok directory (can vary on your system)
45: 
46: {{{# cd /usr/opengrok/bin}}}
47: 
48: and run 
49: 
50: {{{# ./OpenGrok deploy}}}
51: 
52: This command will do some sanity checks and will deploy the source.war in its directory to one of detected web application containers.
53: Please follow the error message it provides.
54: If it fails to discover your container, please refer to optional steps on changing web application properties, which has manual steps on how to do this.
55: 
56: Note that OpenGrok script expects the directory {{code}}/var/opengrok{{/code}} to be available to user running opengrok with all permissions. In root user case it will create all the directories needed, otherwise you have to manually create the directory and grant all permissions to the user used.
57: 
58: ==== Step.2 - Populate DATA_ROOT Directory, let the indexer generate the project XML config file, update configuration.xml to your web app ====
59: 
60: Second step is to just run the indexing (can take a lot of time). After this is done, indexer automatically attempts to upload newly generated configuration to the web application. Most probably you will not be able to use {Opengrok before this is done.
61: 
62: Please change to opengrok directory (can vary on your system)
63: 
64: {{{# cd /usr/opengrok/bin}}}
65: 
66: and run, if your SRC_ROOT is prepared under /var/opengrok/src
67: 
68: {{{# ./OpenGrok index}}}
69: 
70: otherwise (if SRC_ROOT is in different directory) run:
71: 
72: {{{# ./OpenGrok index <absolute_path_to_your_SRC_ROOT>}}}
73: 
74: Above command should try to upload latest index status reflected into configuration.xml to a running source web application.
75: Once above command finishes without errors(e.g. SEVERE: Failed to send configuration to localhost:2424
76: ), you should be able to enjoy your opengrok and search your sources using latest indexes and setup.
77: 
78: Congratulations, you should now be able to point your browser to http://<YOUR_WEBAPP_SERVER>:<WEBAPPSRV_PORT>/source to work with your fresh opengrok installation! :-)
79: 
80: \\
81: 
82: At this time we’d like to point out some customization to OpenGrok script for advanced users.
83: A common case would be, that you want the data in some other directory than /var/opengrok.
84: This can be easily achieved by using environment variable OPENGROK_INSTANCE_BASE .
85: E.g. if my opengrok data directory is /tank/opengrok and my source root is in /tank/source I’d run the indexer as:
86: 
87: {{{# OPENGROK_INSTANCE_BASE=/tank/opengrok ./OpenGrok index /tank/source }}}
88: 
89: A lot more customizations can be found inside the script, you just need to have a look [[at it>>http://src.opensolaris.org/source/xref/opengrok/trunk/OpenGrok]], eventually create a [[configuration>>http://src.opensolaris.org/source/xref/opengrok/trunk/OpenGrok#75]] out of it and use OPENGROK_CONFIGURATION environment variable to point to it. Obviously such setups can be used for nightly cron job updates of index or other automated purposed.
90: 
91: == Optional info ==
92: 
93: === CLI - Command Line Interface Usage ===
94: 
95:  You need to pass location of project file + the query to Search class, e.g. for fulltext search for project with above generated configuration.xml you’d do:
96: 
97: {{{$ java -cp ./opengrok.jar org.opensolaris.opengrok.search.Search -R /var/opengrok/etc/configuration.xml -f fulltext_search_string}}}
98: 
99:  For quick help run:
100: 
101: {{{$ java -cp ./opengrok.jar org.opensolaris.opengrok.search.Search}}}
102: 
103:  Sample search:
104: [[image:CLI-search.png]]
105: 
106: 
107: ==== Optional need to change web application properties or name ====
108: 
109:  You might need to modify the web application if you don’t store the configuration file in the default location ({{code}}/var/opengrok/etc/configuration.xml{{/code}}).
110: 
111: To** configure **the webapp source.war, look into the parameters defined in **WEB-INF/web.xml** of **source.war** (use {{code}}jar{{/code}} or {{code}}zip/unzip{{/code}} or your preffered zip tool to get into it - e.g. extract the web.xml file from source.war ($ unzip source.war WEB-INF/web.xml) file, edit web.xml and re-package the jar file (zip -u source.war WEB-INF/web.xml) ) file and change those web.xml parameters appropriately. These sample parameters need modifying(there are more options, refer to [[manual>>Project opengrok.WebHome]] or read param comments).
112: 
113: * CONFIGURATION - the absolute path to XML file containing project configuration (e.g. /var/opengrok/etc/configuration.xml )
114: * ConfigAddress - port for remote updates to configuration, optional, but **advised(since there is no authentification)** to be set to **localhost**:<some_port> (e.g. localhost:2424), if you choose some_port below 1024 you have to have root privileges
115: 
116: If you need to change name of the web application from source to something else you need to use special option {{code}}-w <new_name>{{/code}} for indexer to create proper xrefs, besides changing the .war file name. Examples below show just deploying source.war, but you can use it to deploy your new_name.war too.
117: 
118: ==== Deploy the modified .war file in glassfish/Sun Java App Server: ====
119: 
120: * **Option 1:** Use browser and log into {{code}}glassfish web administration interface{{/code}}
121: 
122: : Common Tasks / Applications / Web Applications , button **Deploy** and point it to your source.war webarchive
123: 
124: * **Option 2:** Copy the source.war file to //GLASSFISH///domains///YOURDOMAIN///autodeploy directory, glassfish will try to deploy it "automagically".
125: * **Option 3:** Use cli from //GLASSFISH// directory:
126: 
127: {{{# ./bin/asadmin deploy /path/to/source.war}}}
128: 
129: ==== Deploy the modified .war file in tomcat: ====
130: 
131: * just copy the source.war file to //TOMCAT_INSTALL///webapps directory.
132: 
133: ==== Optional setup of security manager for tomcat ====
134: 
135:  On some linux distribution you need to setup permissions for SRC_ROOT and DATA_ROOT. Please check your [[tomcat documentation>>http://tomcat.apache.org/tomcat-5.5-doc/security-manager-howto.html]] on this, or simply disable(your risk!) __security manager__ for tomcat (e.g. in debian/ubuntu : in file /etc/default/tomcat5.5 set TOMCAT5_SECURITY=no ).
136:  A sample approach is to __edit__ /etc/tomcat5.5/04webapps.policy (or /var/apache/tomcat/conf/catalina.policy ) and set this(it will give opengrok all permissions) for your opengrok webapp instance:
137: 
138: {{code}}grant codeBase "file:${catalina.home}/webapps/source/-" {     permission java.security.AllPermission;};
139: grant codeBase "file:${catalina.home}/webapps/source/WEB-INF/lib/-" {     permission java.security.AllPermission;};{{/code}}
140: 
141:  Alternatively you can be more restrictive(haven’t tested below with a complex setup(e.g. some versioning system which needs local access as cvs), if it will not work, please report to [[discuss>>http://www.opensolaris.org/jive/forum.jspa?forumID=117]]):
142: 
143: {{code}}grant codeBase "file:${catalina.home}/webapps/source/-" {  permission java.util.PropertyPermission "subversion.native.library", "read";  permission java.lang.RuntimePermission "loadLibrary.svnjavahl-1?;  permission java.lang.RuntimePermission "loadLibrary.libsvnjavahl-1?;  permission java.lang.RuntimePermission "loadLibrary.svnjavahl";  permission java.util.PropertyPermission "disableLuceneLocks", "read";  permission java.util.PropertyPermission "catalina.home", "read";  permission java.util.PropertyPermission "java.io.tmpdir", "read";  permission java.util.PropertyPermission "org.apache.lucene.lockdir", "read";  permission java.util.PropertyPermission "org.apache.lucene.writeLockTimeout", "read";  permission java.util.PropertyPermission "org.apache.lucene.commitLockTimeout", "read";  permission java.util.PropertyPermission "org.apache.lucene.mergeFactor", "read";  permission java.util.PropertyPermission "org.apache.lucene.minMergeDocs", "read";  permission java.util.PropertyPermission "org.apache.lucene.*", "read";  permission java.io.FilePermission "/var/lib/tomcat5/temp", "read";  permission java.io.FilePermission "/var/lib/tomcat5/temp/*", "write";  permission java.io.FilePermission "/var/lib/tomcat5/temp/*", "delete";};grant codeBase "file:${catalina.home}/webapps/source/WEB-INF/lib/-" {  permission java.util.PropertyPermission "subversion.native.library", "read";  permission java.lang.RuntimePermission "loadLibrary.svnjavahl-1?;  permission java.util.PropertyPermission "disableLuceneLocks", "read";  permission java.util.PropertyPermission "catalina.home", "read";  permission java.util.PropertyPermission "java.io.tmpdir", "read";};grant codeBase "file:${catalina.home}/webapps/source/WEB-INF/classes/-" {  permission java.util.PropertyPermission "subversion.native.library", "read";  permission java.lang.RuntimePermission "loadLibrary.svnjavahl-1?;  permission java.util.PropertyPermission "disableLuceneLocks", "read";  permission java.util.PropertyPermission "catalina.home", "read";  permission java.util.PropertyPermission "java.io.tmpdir", "read";};{{/code}}
144: 
145:  Thanks to Vincent Liu & Flo.
146: 
147: 
148: {{html}}
149: <script type="text/javascript">
150: var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
151: document.write(unescape("%3Cscript src=’" + gaJsHost + "google-analytics.com/ga.js’ type=’text/javascript’%3E%3C/script%3E"));
152: </script>
153: <script type="text/javascript">
154: try {
155: var pageTracker = _gat._getTracker("UA-3665334-1");
156: pageTracker._trackPageview();
157: } catch(err) {}</script>
158: {{/html}}
159:
OpenSolaris

Top Menu

Wiki code for How to install OpenGrok

Search

Project opengrok Pages

Collectives

Community Group

Project

User Group

Subsites
