Documentation. Enforce ".git" suffix for created repositories.

James Moger

2011-06-01 a3bde69e9b3f3cc6212b0cd5fd7310b6a3301d8c

 docs/00_setup.mkd

@@ -1,6 +1,6 @@
## Setup and Configuration

## Server Setup and Configuration



1. Download and unzip [%VERSION%](http://gitblit.com/%DISTRIBUTION%).<br/>

1. Download and unzip [Gitblit %VERSION%](http://gitblit.com/%DISTRIBUTION%).<br/>

*Its best to eliminate spaces in the path name as that can cause troubleshooting headaches.* 

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:

@@ -29,10 +29,15 @@
       showRemoteBranches = false

       accessRestriction = clone

       isFrozen = false

       showReadme = false

       

#### Repository Names

Repository names must be unique and are case-insensitive.  The name must be composed of letters, digits, or `/ _ - .`<br/>

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 by folders.  e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*



Repository names 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.

@@ -48,10 +53,10 @@
Whitespace is illegal.



#### Passwords

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

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 Git:Blit 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 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.



### Creating your own Self-Signed Certificate



@@ -59,8 +64,8 @@
**NOTE:** The certificate password AND the keystore password must match!



### Running as a Service

Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your JVM.<br/>

Set the *JDK* variable in the script to the location of your JDK, add any necessary start parameters, and execute the script.

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.



#### Command-Line Parameters

    --tempFolder           Server temp folder

@@ -74,4 +79,23 @@
    

**Example**



    java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something
    java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something

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



- Eclipse/EGit

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