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
diff --git a/Documentation/config-gitweb.txt b/Documentation/config-gitweb.txt
index 35d5c0d..e5edda8 100644
--- a/Documentation/config-gitweb.txt
+++ b/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 @@
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 @@
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 @@
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
-external web server, and Gerrit access controls are not enforced.
+For the external configuration, gitweb runs under the control of an
+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 favicon
+$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 @@
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 --file $site_path/etc/gerrit.config --unset gitweb.cgi
-====
+----
+$ git config -f $site_path/etc/gerrit.config gitweb.cgi $PATH_TO_GITWEB/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 @@
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 @@
It is also possible to define custom patterns.
See Also
---------
+~~~~~~~~
* link:config-gerrit.html#gitweb[Section gitweb]
* link:http://hjemli.net/git/cgit/[cgit]
