Gitweb Instruction Updates

Added details covering additional instrucitons for installing on Linux
and Windows. This is preparation for the Tomcat instructions.

Bug: Issue 1369
Change-Id: I52b30c0d3c0edd515cf1b2f66eff7b85173b724c

Documentation/config-gitweb.txt

@@ -1,13 +1,12 @@
-Gerrit Code Review - Gitweb Integration
+Gitweb Integration
-=======================================
+------------------
 
 Gerrit Code Review can manage and generate hyperlinks to gitweb,
 allowing users to jump from Gerrit content to the same information,
 but shown by gitweb.
 
-
 Internal/Managed gitweb
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 In the internal configuration, Gerrit inspects the request, enforces
 its project level access controls, and directly executes `gitweb.cgi`
@@ -39,7 +38,7 @@ After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
 be restarted and clients must reload the host page to see the change.
 
 Configuration
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 Most of the gitweb configuration file is handled automatically
 by Gerrit Code Review.  Site specific overrides can be placed in
@@ -47,7 +46,7 @@ by Gerrit Code Review.  Site specific overrides can be placed in
 part of the generated configuration file.
 
 Logo and CSS
-~~~~~~~~~~~~
+^^^^^^^^^^^^
 
 If the package-manager installed CGI (`/usr/lib/cgi-bin/gitweb.cgi`)
 is being used, the stock CSS and logo files will be served from
@@ -58,17 +57,165 @@ in the same directory as the CGI script itself.  This matches with
 the default source code distribution, and most custom installations.
 
 Access Control
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
 
 Access controls for internally managed gitweb page views are enforced
 using the standard project READ +1 permission.
 
-
 External/Unmanaged gitweb
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In the external configuration, gitweb runs under the control of an
+For the external configuration, gitweb runs under the control of an
-external web server, and Gerrit access controls are not enforced.
+external web server, and Gerrit access controls are not enforced. Gerrit
+provides configuration parameters for integration with GitWeb.
+
+[[linuxGitWeb]]
+Linux Installation
+^^^^^^^^^^^^^^^^^^
+
+Install GitWeb
+++++++++++++++
+
+On Ubuntu:
+
+====
+  sudo apt-get install gitweb
+====
+
+With Yum:
+
+====
+  $ yum install gitweb
+====
+
+Configure GitWeb
+++++++++++++++++
+
+
+Update `/etc/gitweb.conf`, add the public GIT repositories:
+
+----
+$projectroot = "/var/www/repo/";
+
+# directory to use for temp files
+$git_temp = "/tmp";
+
+# target of the home link on top of all pages
+#$home_link = $my_uri || "/";
+
+# html text to include at home page
+$home_text = "indextext.html";
+
+# file with project list; by default, simply scan the projectroot dir.
+$projects_list = $projectroot;
+
+# stylesheet to use
+# I took off the prefix / of the following path to put these files inside gitweb directory directly
+$stylesheet = "gitweb.css";
+
+# logo to use
+$logo = "git-logo.png";
+
+# the <20>favicon<6F>
+$favicon = "git-favicon.png";
+----
+
+Configure & Restart Apache Web Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Configure Apache
+++++++++++++++++
+
+
+Link gitweb to `/var/www/gitweb`, check `/etc/gitweb.conf` if unsure of paths:
+
+====
+  $ sudo ln -s /usr/share/gitweb /var/www/gitweb
+====
+
+Add the gitweb directory to the Apache configuration by creating a "gitweb"
+file inside the Apache conf.d directory:
+
+====
+  $ touch /etc/apache/conf.d/gitweb
+====
+
+Add the following to /etc/apache/conf.d/gitweb:
+
+----
+Alias /gitweb /var/www/gitweb
+
+Options Indexes FollowSymlinks ExecCGI
+DirectoryIndex /cgi-bin/gitweb.cgi
+AllowOverride None
+----
+
+*NOTE* This may have already been added by yum/apt-get. If that's the case, leave as
+is.
+
+Restart the Apache Web Server
++++++++++++++++++++++++++++++
+
+====
+$ sudo /etc/init.d/apache2 restart
+====
+
+Now you should be able to view your repository projects online:
+
+link:http://localhost/gitweb[http://localhost/gitweb]
+
+[[WindowsGitWeb]]
+Windows Installation
+^^^^^^^^^^^^^^^^^^^^
+
+Instructions are available for installing the GitWeb module distributed with
+MsysGit:
+
+link:https://github.com/msysgit/msysgit/wiki/GitWeb[GitWeb]
+
+If you don't have Apache installed, you can download the appropriate build for
+Windows from link:http://www.apachelounge.com/download[apachelounge.org].
+
+After you have installed Apache, you will want to create a link:http://httpd.apache.org/docs/2.0/platform/windows.html#winsvc[new service user
+account] to use with Apache.
+
+If you're still having difficulty setting up permissions, you may find this
+tech note useful for configuring Apache Service to run under another account.
+You must grant the new account link:http://technet.microsoft.com/en-us/library/cc794944(WS.10).aspx["run as service"] permission:
+
+The GitWeb version in msysgit is missing several important and required
+perl modules, including CGI.pm. The perl included with the msysgit distro 1.7.8
+is broken.. The link:http://groups.google.com/group/msysgit/browse_thread/thread/ba3501f1f0ed95af[unicore folder is missing along with utf8_heavy.pl and CGI.pm]. You can
+verify by checking for perl modules. From an msys console, execute the
+following to check:
+
+====
+$ perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""
+====
+
+You may encounter the following exception:
+
+----
+$ perl -mCGI -mEncode -mFcntl -mFile::Find -mFile::Basename -e ""
+Can't locate CGI.pm in @INC (@INC contains: /usr/lib/perl5/5.8.8/msys
+/usr/lib/p erl5/5.8.8 /usr/lib/perl5/site_perl/5.8.8/msys
+/usr/lib/perl5/site_perl/5.8.8 /u sr/lib/perl5/site_perl .). BEGIN
+failed--compilation aborted.
+----
+
+If you're missing CGI.pm, you'll have to deploy the module to the msys
+environment: You will have to retrieve them from the 5.8.8 distro on :
+
+http://strawberryperl.com/releases.html
+
+File: strawberry-perl-5.8.8.3.zip
+
+contents: `bin/` `lib/` `site/`
+
+copy the contents of lib into `msysgit/lib/perl5/5.8.8` and overwrite existing files.
+
+Enable GitWeb Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To enable the external gitweb integration, set
 link:config-gerrit.html#gitweb.url[gitweb.url] with the URL of your
@@ -79,16 +226,27 @@ gerrit.basePath, or a fairly current replica.  If a replica is
 being used, ensure it uses a full mirror, so the `refs/changes/*`
 namespace is available.
 
-====
+----
-  git config --file $site_path/etc/gerrit.config gitweb.url http://example.com/gitweb.cgi
+$ git config -f $site_path/etc/gerrit.config gitweb.cgi $PATH_TO_GITWEB/gitweb.cgi
-  git config --file $site_path/etc/gerrit.config --unset gitweb.cgi
+$ git config -f $site_path/etc/gerrit.config gitweb.url https://gitweb.corporation.com
-====
+----
+
+If you're not following the traditional \{projectName\}.git project naming conventions,
+you will want to customize Gerrit to read them. Add the following:
+
+----
+$ git config -f $site_path/etc/gerrit.config gitweb.type custom
+$ git config -f $site_path/etc/gerrit.config gitweb.project ?p=\${project}\;a=summary
+$ git config -f $site_path/etc/gerrit.config gitweb.revision ?p=\${project}\;a=commit\;h=\${commit}
+$ git config -f $site_path/etc/gerrit.config gitweb.branch ?p=\${project}\;a=shortlog\;h=\${branch}
+$ git config -f $site_path/etc/gerrit.config gitweb.filehistory ?p=\${project}\;a=history\;hb=\${branch}\;f=\${file}
+----
 
 After updating `'$site_path'/etc/gerrit.config`, the Gerrit server must
 be restarted and clients must reload the host page to see the change.
 
 Access Control
-~~~~~~~~~~~~~~
+++++++++++++++
 
 Gitweb access controls can be implemented using standard web server
 access controls.  This isn't typically integrated with Gerrit's own
@@ -96,7 +254,7 @@ access controls.  Caution must be taken to ensure the controls are
 consistent if access needs to be restricted.
 
 Caching Gitweb
-~~~~~~~~~~~~~~
+++++++++++++++
 
 If your repository set is large and you are expecting a lot
 of users, you may want to look at the caching forks used by
@@ -112,7 +270,7 @@ cgit can be used by specifying `gitweb.type` to be 'cgit'.
 It is also possible to define custom patterns.
 
 See Also
---------
+~~~~~~~~
 
 * link:config-gerrit.html#gitweb[Section gitweb]
 * link:http://hjemli.net/git/cgit/[cgit]