From d7f53715387c8d8acd2146d338aa68fd47064952 Mon Sep 17 00:00:00 2001 From: jhuntley Date: Wed, 1 Aug 2012 14:19:46 -0400 Subject: [PATCH] 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 | 194 +++++++++++++++++++++++++++++--- 1 file changed, 176 insertions(+), 18 deletions(-) diff --git a/Documentation/config-gitweb.txt b/Documentation/config-gitweb.txt index 35d5c0d7e5..e5edda808b 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 @@ 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 -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 @@ 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 --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 @@ 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]