## Gitblit WAR Setup

1. Download [Gitblit WAR %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) to the webapps folder of your servlet container.<br/>
2. You may have to manually extract the WAR (zip file) to a folder within your webapps folder.
3. Copy the `WEB-INF/users.properties` file to a location outside the webapps folder that is accessible by your servlet container.  
4. The Gitblit webapp is configured through its `web.xml` file.<br/>
Open `web.xml` in your favorite text editor and make sure to review and set:
    - &lt;context-parameter&gt; *git.repositoryFolder* (set the full path to your repositories folder)
    - &lt;context-parameter&gt; *realm.userService* (set the full path to `users.properties`)
5. You may have to restart your servlet container. 
6. Open your browser to <http://localhost/gitblit> or whatever the url should be.
7. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>
    **NOTE:** Make sure to change the administrator username and/or password!! 

## Gitblit GO Setup

1. Download and unzip [Gitblit GO %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%GO%).<br/>
*Its best to eliminate spaces in the path name.* 
2. The server itself is configured through a simple text file.<br/>
Open `gitblit.properties` in your favorite text editor and make sure to review and set:
    - *git.repositoryFolder* (path may be relative or absolute)
    - *server.tempFolder* (path may be relative or absolute)
    - *server.httpBindInterface* and *server.httpsBindInterface*<br/>
    **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!     
3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line
4. Wait a minute or two while all dependencies are downloaded and your self-signed *localhost* certificate is generated.<br/>Please see the section titled **Creating your own Self-Signed Certificate** to generate a certificate for *your hostname*.
5. Open your browser to <http://localhost> or <https://localhost> depending on your chosen configuration.
6. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>
    **NOTE:** Make sure to change the administrator username and/or password!! 

### Creating your own Self-Signed Certificate
Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.

Remote Eclipse/EGit/JGit clients (<= 1.0.0) will fail to communicate using this certificate because JGit always verifies the hostname of the certificate, regardless of the *http.sslVerify=false* client-side setting.

The EGit failure message is something like:

	Cannot get remote repository refs.
	Reason: https:/myserver.com/git/myrepo.git: cannot open git-upload-pack

If you want to serve your repositories to another machine over https then you will want to generate your own certificate.

1. Review the contents of `makekeystore.cmd` or `makekeystore_jdk.cmd`
2. Set *your hostname* into the *HOSTNAME* variable.
3. Execute the script.<br/>This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*.
 
**NOTE:**<br/>If you use `makekeystore_jdk.cmd`, the certificate password AND the keystore password must match and must be set as *server.storePassword* or specified with the *storePassword* command-line parameter!

Additionally, if you want to change the value of *server.storePassword* (recommended) you will have to generate a new certificate afterwards.

### Running as a Windows Service
Gitblit uses [Apache Commons Daemon](http://commons.apache.org/daemon) to install and configure its Windows service.

1. Review the contents of the `installService.cmd`
2. Set the *ARCH* value as appropriate for your installed Java Virtual Machine.<br/>
3. Add any necessary *--StartParams* as enumerated below in **Command-Line Parameters**.
4. Execute the script.

After service installation you can use the `gitblitw.exe` utility to control and modify the runtime settings of the service.<br/>
Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html).

**NOTE:**<br/>
If you change the name of the service from *gitblit* you must also change the name of `gitblitw.exe` to match the new service name otherwise the connection between the service and the utility is lost, at least to double-click execution. 

#### Command-Line Parameters
Command-Line parameters override the values in `gitblit.properties` at runtime.

	--repositoriesFolder   Git Repositories Folder
    --userService          Authentication and Authorization Service (filename or fully qualified classname)
    --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)
    --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
    
**Example**

    java -jar gitblit.jar --userService c:\myrealm.properties --storePassword something
    
## Gitblit Configuration

### Administering Repositories
Repositories can be created, edited, renamed, and deleted through the web UI.  They may also be created, edited, and deleted from the command-line using real [Git](http://git-scm.com) or your favorite file manager and text editor.

All repository settings are stored within the repository `.git/config` file under the *gitblit* section.

    [gitblit]
	    description = master repository
	    owner = james
	    useTickets = false
	    useDocs = true
	    showRemoteBranches = false
	    accessRestriction = clone
	    isFrozen = false
	    showReadme = false
	    
#### Repository Names
Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS.  The name must be composed of letters, digits, or `/ _ - .`<br/>
Whitespace is illegal.

Repositories can be grouped within subfolders.  e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*

All repositories created with Gitblit are *bare* and will automatically have *.git* appended to the name at creation time, if not already specified. 

#### Repository Owner
The *Repository Owner* has the special permission of being able to edit a repository through the web UI.  The Repository Owner is not permitted to rename the repository, delete the repository, or reassign ownership to another user.

### Administering Users
All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`.<br/>
The format of `users.properties` follows Jetty's convention for HashRealms:

    username,password,role1,role2,role3...

#### Usernames
Usernames must be unique and are case-insensitive.<br/>
Whitespace is illegal.

#### Passwords
User passwords are CASE-SENSITIVE and may be *plain* or *md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).

#### User Roles
There is only one actual *role* in Gitblit and that is *#admin* which grants administrative powers to that user.  Administrators automatically have access to all repositories.  All other *roles* are repository names.  If a repository is access-restricted, the user must have the repository's name within his/her roles to bypass the access restriction.  This is how users are granted access to a restricted repository.

## Authentication and Authorization Customization
Instead of maintaining a `users.properties` file, you may want to integrate Gitblit into an existing environment.

You may use your own custom *com.gitblit.IUserService* implementation by specifying its fully qualified classname in the *realm.userService* setting.<br/>

Your user service class must be on Gitblit's classpath and must have a public default constructor. 

## Client Setup and Configuration
### Https with Self-Signed Certificates
You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.

**NOTE:**<br/>
The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.<br/>
If you are using Eclipse/EGit/JGit clients, you will have to generate your own certificate that specifies the exact hostname used in your clone/push url.<br/>
You must do this because Eclipse/EGit/JGit (<= 1.0.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. 
 
- Eclipse/EGit/JGit
    1. Window->Preferences->Team->Git->Configuration
    2. Click the *New Entry* button
    3. <pre>Key = *http.sslVerify*       
       Value = *false*</pre>
- Command-line Git ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
    <pre>git config --global --bool --add http.sslVerify false</pre>

### Cloning an Access Restricted Repository 
- Eclipse/EGit/JGit<br/>Nothing special to configure, EGit figures out everything.
    <pre>https://yourserver/git/your/repository</pre>
- Command-line Git<br/>*My testing indicates that your username must be embedded in the url.  YMMV.*
    <pre>https://username@yourserver/git/your/repository</pre>