Documentation

James Moger

2012-12-05 dc9735acfc9dcea6b970d18a315cbf8a6997c4f9

Documentation

 docs/01_features.mkd

@@ -17,7 +17,7 @@
- Optional feature to allow users to create personal repositories

- Optional feature to fork a repository to a personal repository

- Optional feature to create a repository on push

- Experimental built-in Garbage Collection

- *Experimental* built-in Garbage Collection

- Ability to federate with one or more other Gitblit instances

- RSS/JSON RPC interface

- Java/Swing Gitblit Manager tool 

@@ -59,8 +59,8 @@


## Gitblit GO Features

- Out-of-the-box integrated stack requiring minimal configuration

- Automatically generates a self-signed certificate for *localhost* https communications  
    (includes script to generate a self-signed certificate for *your hostname*, see [setup](/setup.html) for details)

- Automatic generation of ssl certificate for https communications

- Integrated GUI tool to facilitate x509 PKI including ssl and client certificate generation, client certificate revocation, and client certificate distribution

- Single text file for configuring server and gitblit

- A Windows service installation script and configuration tool

- Built-in AJP connector for Apache httpd 


 docs/01_setup.mkd

@@ -27,7 +27,6 @@
    - *git.repositoryFolder* (path may be relative or absolute)

    - *groovy.scriptsFolder* (path may be relative or absolute)

    - *groovy.grapeFolder* (path may be relative or absolute)

    - *web.siteName* (used in certificate generation, etc)

    - *server.tempFolder* (path may be relative or absolute)

    - *server.httpPort* and *server.httpsPort*

    - *server.httpBindInterface* and *server.httpsBindInterface*  

@@ -36,10 +35,10 @@
    - *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 -jar authority.jar` from a command-line

    a. enter default values for your generated certificates in the *new certificate defaults* dialog

    b. enter the store password used in *server.storePassword* when prompted *(this generates an SSL certificate for **localhost**)*

    c. you will also want to generate SSL certificates for the hostnames or ip addresses you serve from

    d. exit the authority app

    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<br/>**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` 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    

@@ -55,18 +54,21 @@
    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.

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`

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. Enter the *server.storePassword* password

4. Make sure the checkbox *serve https with this certificate* is checked

5. In the keystore password prompt, enter the *server.storePassword* password

 

Additionally, if you want to change the value of *server.storePassword* (recommended) you will have to delete the following files and then start the Gitblit Certificate Authority app:

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. serverKeyStore.jks

2. serverTrustStore.jks

3. certs/caKeyStore.jks

4. certs/ca.crt

5. certs/caRevocationList.crl (optional)



### Client SSL Certificates

SINCE 1.2.0

@@ -94,8 +96,12 @@


1. `authority.cmd` or `java -jar authority.jar`

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.

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.

@@ -130,6 +136,7 @@
    --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


 docs/04_releases.mkd

@@ -42,6 +42,7 @@
Personal repositories can be created by accounts with the *create* permission and are stored in *git.repositoriesFolder/~username*.  Each user with personal repositories will have a user page, something like the GitHub profile page.  Personal repositories have all the same features as common repositories, except personal repositories can be renamed by their owner.

- Added support for server-side forking of a repository to a personal repository (issue 137)

In order to fork a repository, the user account must have the *fork* permission **and** the repository must *allow forks*.  The clone inherits the access list of its origin.  i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork.  This is to facilitate collaboration.  The fork owner may change access to the fork and add/remove users/teams, etc as required <u>however</u> it should be noted that all personal forks will be enumerated in the fork network regardless of access view restrictions.  If you really must have an invisible fork, the clone it locally, create a new repository for your invisible fork, and push it back to Gitblit.

    **New:** *web.allowForking=true*

- Added optional *create-on-push* support

    **New:** *git.allowCreateOnPush=true*

- Added **experimental** JGit-based garbage collection service.  This service is disabled by default.

@@ -58,7 +59,7 @@
- Added support for Gitblit GO to require usage of client certificates to access the entire server.

This is extreme and should be considered carefully since it affects every https access.  The default is to **want** client certificates.  Setting this value to *true* changes that to **need** client certificates.

    **New:** *server.requireClientCertificates = false*

- Added Gitblit Certificate Authority, an X509 certificate generation tool for Gitblit GO to encourage use of client certificate authentication.

- Added **Gitblit Certificate Authority**, an x509 PKI management tool for Gitblit GO to encourage use of x509 client certificate authentication.

- Added setting to control length of shortened commit ids

    **New:** *web.shortCommitIdLength=8*

- Added alternate compressed download formats: tar.gz, tar.xz, tar.bzip2 (issue 174)