Whoops. Missed adding LucenePage.

James Moger

2012-03-02 4c13bf3ccd19a58c55f60bc28986b901d1cebf77

 docs/01_setup.mkd

@@ -86,6 +86,7 @@
    --useNio               Use NIO Connector else use Socket Connector.

    --httpPort             HTTP port for to serve. (port <= 0 will disable this connector)

    --httpsPort            HTTPS port to serve.  (port <= 0 will disable this connector)

    --ajpPort              AJP port to serve.  (port <= 0 will disable this connector)

    --storePassword        Password for SSL (https) keystore.

    --shutdownPort         Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor)

    --tempFolder           Folder for server to extract built-in webapp

@@ -93,6 +94,76 @@
**Example**



    java -jar gitblit.jar --userService c:\myrealm.config --storePassword something



#### Overriding Gitblit GO's Log4j Configuration



You can override Gitblit GO's default Log4j configuration with a command-line parameter to the JVM.



    java -Dlog4j.configuration=file:///home/james/log4j.properties -jar gitblit.jar <optional_gitblit_args>

    
For reference, here is [Gitblit's default Log4j configuration](https://github.com/gitblit/gitblit/blob/master/src/log4j.properties).  It includes some file appenders that are disabled by default. 
    
## Running Gitblit behind Apache



Gitblit runs fine behind Apache.  You may use either *mod_proxy* (GO or WAR) or *mod_proxy_ajp* (GO).



Each Linux distribution may vary on the exact configuration of Apache 2.2.  
Here is a sample configuration that works on Debian 7.0 (Wheezy), your distribution may be different.



1. First we need to make sure we have Apache's proxy modules available.  
<pre>

sudo su

cd /etc/apache2/mods-enabled

ln -s ../mods-available/proxy.load proxy.load

ln -s ../mods-available/proxy_balancer.load proxy_balancer.load

ln -s ../mods-available/proxy_http.load proxy_http.load

ln -s ../mods-available/proxy_ajp.load proxy_ajp.load

</pre>

2. Then we need to make sure we are configuring Apache to use the proxy modules and to setup the proxied connection from Apache to Gitblit GO or from Apache to your chosen servlet container.  The following snippet is stored as `/etc/apache2/conf.d/gitblit`.  
%BEGINCODE%

# Turn off support for true Proxy behaviour as we are acting as 
# a transparent proxy

ProxyRequests Off



# Turn off VIA header as we know where the requests are proxied

ProxyVia Off

 
# Turn on Host header preservation so that the servlet container

# can write links with the correct host and rewriting can be avoided.

#

# This is important for all git push/pull/clone operations.

ProxyPreserveHost On

 
# Set the permissions for the proxy

&lt;Proxy *&gt;

   AddDefaultCharset off

   Order deny,allow

   Allow from all

&lt;/Proxy&gt;

 
# Turn on Proxy status reporting at /status

# This should be better protected than: Allow from all

ProxyStatus On

&lt;Location /status&gt;

   SetHandler server-status

   Order Deny,Allow

   Allow from all

&lt;/Location&gt;



# The proxy context path must match the Gitblit context path.

# For Gitblit GO, see server.contextPath in gitblit.properties.



#ProxyPass /gitblit http://localhost:8080/gitblit

#ProxyPass /gitblit ajp://localhost:8009/gitblit

%ENDCODE%  
**Please** make sure to:  
    1. Review the security of these settings as appropriate for your deployment

    2. Uncomment the *ProxyPass* setting for whichever connection you prefer (http/ajp)

    3. Correctly set the ports and context paths both in the *ProxyPass* definition and your Gitblit installation  
    If you are using Gitblit GO you can easily configure the AJP connector by specifying a non-zero AJP port.  
    Please remember that on Linux/UNIX, ports < 1024 require root permissions to open.

    4. Set *web.mountParameters=false* in `gitblit.properties` or `web.xml` this will use parameterized URLs.  
    Alternatively, you can respecify *web.forwardSlashCharacter*.



## Upgrading Gitblit

Generally, upgrading is easy.

@@ -196,6 +267,7 @@
      user = babaracus

      repository = topsecret.git

      mailingList = list@ateam.org

      postReceiveScript = sendmail



The `users.conf` file allows flexibility for adding new fields to a UserModel object that the original `users.properties` file does not afford without imposing the complexity of relying on an embedded SQL database. 



@@ -241,7 +313,7 @@


*SINCE 0.8.0*



The preferred hook mechanism is Groovy.  This mechanism only executes when pushing to Gitblit, not when pushing to some other Git tooling in your stack.

Gitblit uses Groovy for its push hook mechanism.  This mechanism only executes when pushing to Gitblit, not when pushing to some other Git tooling in your stack.



The Groovy hook mechanism allows for dynamic extension of Gitblit to execute custom tasks on receiving and processing push events.  The scripts run within the context of your Gitblit instance and therefore have access to Gitblit's internals at runtime.



@@ -251,13 +323,14 @@
3. Script filenames must not have spaces!

4. Scripts must be explicitly specified to be executed, no scripts are *automatically* executed by name or extension.

5. A script can be specified to run on *all repositories* by adding the script file name to *groovy.preReceiveScripts* or *groovy.postReceiveScripts* in `gitblit.properties` or `web.xml`.

6. Scripts may also be specified per-repository in the repository's settings.

7. Globally specified scripts are excluded from the list of available scripts in a repository's settings 
8. Globally specified scripts are executed first, in their listed order, followed by per-repository scripts, in their listed order.

9. A script may only be defined once in a pre-receive chain and once in a post-receive chain.  
6. Scripts can be specified for a team.

7. Scripts may also be specified per-repository in the repository's settings.

8. Globally-specified scripts and team-specified scripts are excluded from the list of available scripts in a repository's settings 
9. Globally-specified scripts are executed first, in their listed order; followed by team-specified scripts in their listed order by alphabetical team order; followed by per-repository scripts, in their listed order.

10. A script may only be defined once in a pre-receive chain and once in a post-receive chain.  
You may execute the same script on pre-receive and post-receive, just not multiple times within a pre-receive or post-receive event.

10. Gitblit does not differentiate between what can be a pre-receive script and what can be a post-receive script.

11. If a script *returns false* then the hook chain is aborted and none of the subsequent scripts will execute.

11. Gitblit does not differentiate between what can be a pre-receive script and what can be a post-receive script.

12. If a script *returns false* then the hook chain is aborted and none of the subsequent scripts will execute.



Some sample scripts are included in the GO and WAR distributions to show you how you can tap into Gitblit with the provided bound variables.  Additional implementation details may be specified in the header comment of these examples.



@@ -282,10 +355,11 @@
### Enabling Push Notifications



In order to send email notifications on a push to Gitblit, this script must be specified somewhere in the *post-receive* script chain.  

You may specify *sendmail* in one of two places:

You may specify *sendmail* in one of three places:



1. *groovy.postReceiveScripts* in `gitblit.properties` or `web.xml`, globally applied to all repositories

2. post-receive scripts of a Repository definition

2. post-receive scripts of a Team definition

3. post-receive scripts of a Repository definition



### Destination Addresses