gitblit/src/site/setup_go.mkd

## Gitblit GO Installation & Setup

1. Download and unzip Gitblit GO [${project.releaseVersion} (Windows)](%GCURL%gitblit-${project.releaseVersion}.zip) or [${project.releaseVersion} (Linux/OSX)](%GCURL%gitblit-${project.releaseVersion}.tar.gz).  
*Its best to eliminate spaces in the path name.* 
2. The server itself is configured through a simple text file.
Open `data/gitblit.properties` in your favorite text editor and make sure to review and set:
    - *server.httpPort* and *server.httpsPort*
    - *server.storePassword*
    **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!
    - *git.packedGitLimit* (set larger than the size of your largest repository)
    - *git.streamFileThreshold* (set larger than the size of your largest committed file)
3. Execute `authority.cmd` or `java -cp gitblit.jar com.gitblit.authority.Launcher --baseFolder data` from a command-line
**NOTE:** The Authority is a Swing GUI application.  Use of this tool is not required as Gitblit GO will startup and create SSL certificates itself, BUT use of this tool allows you to control the identification metadata used in the generated certificates.  Skipping this step will result in certificates with default metadata.
    1. fill out the fields in the *new certificate defaults* dialog
	2. enter the store password used in *server.storePassword* when prompted.  This generates an SSL certificate for **localhost**.
	3. you may want to generate an SSL certificate for the hostname or ip address hostnames you are serving from
	**NOTE:** You can only have **one** SSL certificate specified for a port.
	5. exit the authority app
4. Execute `gitblit.cmd` or `java -jar gitblit.jar --baseFolder data` from a command-line
5. Open your browser to <http://localhost:8080> or <https://localhost:8443> depending on your chosen configuration.
6. Enter the default administrator credentials: **admin / admin** and click the *Login* button    
    **NOTE:** Make sure to change the administrator username and/or password!! 

### GO Data Location

By default, Gitblit GO stores all data (users, settings, repositories, etc) in the `data` subfolder of your GO installation.  You may specify an external location for your data on the command-line by setting the *--baseFolder* argument.  If you relocate the data folder then you must supply the *--baseFolder* argument to both GO and the Certificate Authority.

If you are deploying Gitblit to a *nix platform, you might consider moving the data folder out of the GO installation folder and then creating a symlink named "data" that points to your moved folder.

### Creating your own Self-Signed SSL Certificate
Gitblit GO (and Gitblit Certificate Authority) automatically generates a Certificate Authority (CA) certificate and an ssl certificate signed by this CA certificate that is bound to *localhost*.

Remote Eclipse/EGit/JGit clients (< 3.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 a new certificate for the hostname or ip address you are serving from.

1. `authority.cmd` or `java -jar authority.jar --baseFolder data`
2. Click the *new ssl certificate* button (red rosette in the toolbar in upper left of window)
3. Enter the hostname or ip address
4. Make sure the checkbox *serve https with this certificate* is checked
5. In the keystore password prompt, enter the *server.storePassword* password
 
If you decide to change the value of *server.storePassword* (recommended) <u>after</u> you have already started Gitblit or Gitblit Certificate Authority, then you will have to delete the following files and then restart the Gitblit Certificate Authority app:

1. data/serverKeyStore.jks
2. data/serverTrustStore.jks
3. data/certs/caKeyStore.jks
4. data/certs/ca.crt
5. data/certs/caRevocationList.crl (optional)

### Client SSL Certificates
SINCE 1.2.0

Gitblit supports X509 certificate authentication.  This authentication method relies on your servlet container to validate/verify/trust your client certificate and can be used by your browser and your git client.

All X509 certificates have a *distinguished name (DN)* which is a signature of several fields like:

    C=US,O=Gitblit,OU=Gitblit,CN=james
	
Gitblit must be able to map the DN of the certificate to an *existing* account username.  The default mapping is to extract the *common name (CN)* value from the DN and use that as the account name.  If the CN is a valid account, then the user is authenticated.  The servlet container which runs Gitblit validates, verifies, and trusts the certificate passed to Gitblit.  If you need to specify an alternative DN mapping you may do so with the *git.certificateUsernameOIDs* setting, but this mapping must be matched to the user account name.

How do you make your servlet container trust a client certificate?

In the WAR variant, you will have to manually setup your servlet container to:

1. want/need client certificates
2. trust a CA certificate used to sign your client certificates
3. generate client certificates signed by your CA certificate

Alternatively, Gitblit GO is designed to facilitate use of client certificate authentication.  Gitblit GO ships with a tool that simplifies creation and management of client certificates, Gitblit Certificate Authority.

#### Creating SSL Certificates with Gitblit Certificate Authority

When you generate a new client certificate, a zip file bundle is created which includes a P12 keystore for browsers and a PEM keystore for Git.  Both of these are password-protected.  Additionally, a personalized README file is generated with setup instructions for popular browsers and Git.  The README is generated from `data\certs\instructions.tmpl` and can be modified to suit your needs.

1. `authority.cmd` or `java -jar authority.jar --baseFolder data`
2. Select the user for which to generate the certificate
3. Click the *new certificate* button and enter the expiration date of the certificate.  You must also enter a password for the generated keystore.  This password is *not* the same as the user's login password.  This password is used to protect the privatekey and public certificate you will generate for the selected user.  You must also enter a password hint for the user.
4. If your mail server settings are properly configured you will have a *send email* checkbox which you can use to immediately send the generated certificate bundle to the user.

#### Certificate Inspection and Advanced Troubleshooting

X509 certificates can be confusing and tricky even with the simplified Gitblit Certificate Authority tool.  If you find you need more tooling to understand your keystores, certificates, and certificate revocation lists (CRLs), I highly recommend [Portecle](http://portecle.sourceforge.net) which can be conveniently launched as a [Java Web Start app](http://portecle.sourceforge.net/webstart/portecle.jnlp).

### 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` where you may have to change the <u>default keystore password</u>.
2. Set the *ARCH* value as appropriate for your installed Java Virtual Machine.
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.
Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html).

**NOTE:**
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. 

#### VM Considerations
By default, the service installation script configures your Windows service to use your default JVM.  This setup usually defaults to a client VM.
If you have installed a JDK, you might consider using the `gitblitw.exe` utility to manually specify the *server* VM.

1. Execute `gitblitw.exe`
2. On the *Java* tab uncheck *Use default*.
3. Manually navigate your filesystem and specify the server VM with the `...` button
<pre>Java Virtual Machine:
C:\Program Files\Java\jre6\bin\server\jvm.dll</pre>

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

    --baseFolder           The default base folder for all relative file reference settings
    --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)
    --ajpPort              AJP port to serve.  (port <= 0 will disable this connector)
    --alias                Alias in keystore of SSL cert to use for https serving
    --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.config --storePassword something --baseFolder c:/data

#### 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.