Organized imports

James Moger

2011-10-26 17f9de759bb24611252951e2b351373f9c446077

 docs/01_setup.mkd

@@ -1,46 +1,79 @@
## 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.  Manual extraction depends on if your servlet container is configured to automatically deploy WAR files.

3. Copy the `WEB-INF/users.properties` file to a location outside the webapps folder but accessible by your servlet container.  
4. The Gitblit webapp is configured through its `web.xml` file.<br/>

1. Download [Gitblit WAR %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) to the webapps folder of your servlet container.  
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.  
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!! 
7. Enter the default administrator credentials: **admin / admin** and click the *Login* button  
    **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/>

1. Download and unzip [Gitblit GO %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%GO%).  
*Its best to eliminate spaces in the path name.* 

2. The server itself is configured through a simple text file.<br/>

2. The server itself is configured through a simple text file.  
Open `gitblit.properties` in your favorite text editor and make sure to review and set:

    - *git.repositoryFolder* (path my be relative or absolute)

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

    - *server.httpBindInterface* and *server.httpsBindInterface*<br/>

**NOTE:** Consider using **https** exclusively because passwords for authentication are transmitted as clear text!     
    - *server.storePassword*<br/>

**NOTE:** If you manually generate an ssl certificate, the certificate password AND the keystore password must match!     
    - *git.repositoryFolder* (path may be relative or absolute)

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

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

    - *server.httpBindInterface* and *server.httpsBindInterface*  
    **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 certificate is generated.

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!! 
4. Wait a minute or two while all dependencies are downloaded and your self-signed *localhost* certificate is generated.  
    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: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!! 


### Creating your own Self-Signed Certificate

Gitblit GO automatically generates an ssl certificate for you that contains generic, non-personalized information.

Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.



Should you want to include more personal or server-specific information in your self-signed certificate you will have to generate a new one.

Remote Eclipse/EGit/JGit clients (<= 1.1.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*.

 

Review the contents of the `makekeystore.cmd` or `makekeystore_jdk.cmd` script and execute it.<br/>

**NOTE:** If you manually generate an ssl certificate, the certificate password AND the keystore password must match!

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

Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your installed Java Virtual Machine.<br/>

Set the *JVM* variable in the script to the location of your Java Virtual Machine, add any necessary start parameters, and execute the script.

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.

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. 


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

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<br/><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.

@@ -57,7 +90,32 @@
**Example**



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

    


## Upgrading Gitblit

Generally, upgrading is easy.



Since Gitblit does not use a database the only files you have to worry about are your configuration file (`gitblit.properties` or `web.xml`) and possibly your `users.properties` file.



Any important changes to the setting keys or default values will always be mentioned in the [release log](releases.html).



### Upgrading Gitblit WAR

1. Backup your `web.xml` file

2. Delete currently deployed gitblit WAR

3. Deploy new WAR and overwrite the `web.xml` file with your backup

4. Review and optionally apply any new settings as indicated in the [release log](releases.html). 
 
### Upgrading Gitblit GO

 
1. Backup your `gitblit.properties` file

2. Backup your `users.properties` file *(if it is located in the Gitblit GO folder)*

3. Unzip Gitblit GO to a new folder

4. Overwrite the `gitblit.properties` file with your backup

5. Overwrite the `users.properties` file with your backup *(if it was located in the Gitblit GO folder)*

6. Review and optionally apply any new settings as indicated in the [release log](releases.html).



#### Upgrading Windows Service

You may need to delete your old service definition and install a new one depending on what has changed in the release.



## Gitblit Configuration



### Administering Repositories

@@ -74,7 +132,11 @@
       accessRestriction = clone

       isFrozen = false

       showReadme = false

	    
       federationStrategy = FEDERATE_THIS

       isFederated = false

       skipSizeCalculation = false

       federationSets = 


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

@@ -93,37 +155,185 @@
    username,password,role1,role2,role3...



#### Usernames

Usernames must be unique and are case-insensitive.<br/>

Usernames must be unique and are case-insensitive.  
Whitespace is illegal.



#### Passwords

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

User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-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.

There are two actual *roles* in Gitblit: *#admin*, which grants administrative powers to that user, and *#notfederated*, which prevents an account from being pulled by another Gitblit instance.  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/>

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



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



%BEGINCODE%

public interface IUserService {



   /**

    * Setup the user service.

    * 
    * @param settings

    * @since 0.7.0

    */

   @Override

   public void setup(IStoredSettings settings) {

   }

	
   /**

    * Does the user service support cookie authentication?

    * 
    * @return true or false

    */

   boolean supportsCookies();



   /**

    * Returns the cookie value for the specified user.

    * 
    * @param model

    * @return cookie value

    */

   char[] getCookie(UserModel model);



   /**

    * Authenticate a user based on their cookie.

    * 
    * @param cookie

    * @return a user object or null

    */

   UserModel authenticate(char[] cookie);



   /**

    * Authenticate a user based on a username and password.

    * 
    * @param username

    * @param password

    * @return a user object or null

    */

   UserModel authenticate(String username, char[] password);



   /**

    * Retrieve the user object for the specified username.

    * 
    * @param username

    * @return a user object or null

    */

   UserModel getUserModel(String username);



   /**

    * Updates/writes a complete user object.

    * 
    * @param model

    * @return true if update is successful

    */

   boolean updateUserModel(UserModel model);



   /**

    * Adds/updates a user object keyed by username. This method allows for

    * renaming a user.

    * 
    * @param username

    *            the old username

    * @param model

    *            the user object to use for username

    * @return true if update is successful

    */

   boolean updateUserModel(String username, UserModel model);



   /**

    * Deletes the user object from the user service.

    * 
    * @param model

    * @return true if successful

    */

   boolean deleteUserModel(UserModel model);



   /**

    * Delete the user object with the specified username

    * 
    * @param username

    * @return true if successful

    */

   boolean deleteUser(String username);



   /**

    * Returns the list of all users available to the login service.

    * 
    * @return list of all usernames

    */

   List<String> getAllUsernames();



   /**

    * Returns the list of all users who are allowed to bypass the access

    * restriction placed on the specified repository.

    * 
    * @param role

    *            the repository name

    * @return list of all usernames that can bypass the access restriction

    */

   List<String> getUsernamesForRepositoryRole(String role);



   /**

    * Sets the list of all uses who are allowed to bypass the access

    * restriction placed on the specified repository.

    * 
    * @param role

    *            the repository name

    * @param usernames

    * @return true if successful

    */

   boolean setUsernamesForRepositoryRole(String role, List<String> usernames);



   /**

    * Renames a repository role.

    * 
    * @param oldRole

    * @param newRole

    * @return true if successful

    */

   boolean renameRepositoryRole(String oldRole, String newRole);



   /**

    * Removes a repository role from all users.

    * 
    * @param role

    * @return true if successful

    */

   boolean deleteRepositoryRole(String role);



   /**

    * @See java.lang.Object.toString();

    * @return string representation of the login service

    */

   String toString();

}

%ENDCODE%



## Client Setup and Configuration

### Https with Self-Signed Certificates

You must tell Git not to verify the self-signed certificate in order to perform any remote Git operations.

You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.



- Eclipse/EGit

**NOTE:**  
The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.  
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.  
You must do this because Eclipse/EGit/JGit (<= 1.1.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>

    3. <pre>Key = <em>http.sslVerify</em>

Value = <em>false</em></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<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>

           
- **Eclipse/EGit/JGit**  
Nothing special to configure, EGit figures out everything.

<pre>https://yourserver/git/your/repository</pre>

- **Command-line Git**  
My testing indicates that your username must be embedded in the url.  YMMV.  
<pre>https://username@yourserver/git/your/repository</pre>