Gitblit devel
view | history | commit | commitdiff
James Moger
2011-06-28 d39680e9f54322ddcb40b00503a8ee30aee6c99c
commit | author | age
85c2e6 1 ## Gitblit WAR Setup
dd7961 2
85c2e6 3 1. Download [Gitblit WAR %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%) to the webapps folder of your servlet container.<br/>
d39680 4 2. You may have to manually extract the WAR (zip file) to a folder within your webapps folder.
JM 5 3. Copy the `WEB-INF/users.properties` file to a location outside the webapps folder that is accessible by your servlet container.  
85c2e6 6 4. The Gitblit webapp is configured through its `web.xml` file.<br/>
JM 7 Open `web.xml` in your favorite text editor and make sure to review and set:
8     - &lt;context-parameter&gt; *git.repositoryFolder* (set the full path to your repositories folder)
9     - &lt;context-parameter&gt; *realm.userService* (set the full path to `users.properties`)
10 5. You may have to restart your servlet container. 
11 6. Open your browser to <http://localhost/gitblit> or whatever the url should be.
12 7. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>
d39680 13     **NOTE:** Make sure to change the administrator username and/or password!! 
85c2e6 14
JM 15 ## Gitblit GO Setup
16
17 1. Download and unzip [Gitblit GO %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%GO%).<br/>
18 *Its best to eliminate spaces in the path name.* 
dd7961 19 2. The server itself is configured through a simple text file.<br/>
JM 20 Open `gitblit.properties` in your favorite text editor and make sure to review and set:
d39680 21     - *git.repositoryFolder* (path may be relative or absolute)
JM 22     - *server.tempFolder* (path may be relative or absolute)
00afd7 23     - *server.httpBindInterface* and *server.httpsBindInterface*<br/>
d39680 24     **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!     
dd7961 25 3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line
d39680 26 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*.
dd7961 27 5. Open your browser to <http://localhost> or <https://localhost> depending on your chosen configuration.
JM 28 6. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>
d39680 29     **NOTE:** Make sure to change the administrator username and/or password!! 
85c2e6 30
JM 31 ### Creating your own Self-Signed Certificate
d39680 32 Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.
85c2e6 33
d39680 34 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.
JM 35
36 The EGit failure message is something like:
37
38     Cannot get remote repository refs.
39     Reason: https:/myserver.com/git/myrepo.git: cannot open git-upload-pack
40
41 If you want to serve your repositories to another machine over https then you will want to generate your own certificate.
42
43 1. Review the contents of `makekeystore.cmd` or `makekeystore_jdk.cmd`
44 2. Set *your hostname* into the *HOSTNAME* variable.
45 3. Execute the script.<br/>This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*.
85c2e6 46  
d39680 47 **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!
JM 48
49 Additionally, if you want to change the value of *server.storePassword* (recommended) you will have to generate a new certificate afterwards.
85c2e6 50
JM 51 ### Running as a Windows Service
d39680 52 Gitblit uses [Apache Commons Daemon](http://commons.apache.org/daemon) to install and configure its Windows service.
JM 53
54 1. Review the contents of the `installService.cmd`
55 2. Set the *ARCH* value as appropriate for your installed Java Virtual Machine.<br/>
56 3. Add any necessary *--StartParams* as enumerated below in **Command-Line Parameters**.
57 4. Execute the script.
58
59 After service installation you can use the `gitblitw.exe` utility to control and modify the runtime settings of the service.<br/>
60 Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html).
61
62 **NOTE:**<br/>
63 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. 
85c2e6 64
JM 65 #### Command-Line Parameters
66 Command-Line parameters override the values in `gitblit.properties` at runtime.
67
68     --repositoriesFolder   Git Repositories Folder
69     --userService          Authentication and Authorization Service (filename or fully qualified classname)
70     --useNio               Use NIO Connector else use Socket Connector.
71     --httpPort             HTTP port for to serve. (port <= 0 will disable this connector)
72     --httpsPort            HTTPS port to serve.  (port <= 0 will disable this connector)
73     --storePassword        Password for SSL (https) keystore.
74     --shutdownPort         Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor)
75     --tempFolder           Folder for server to extract built-in webapp
76     
77 **Example**
78
79     java -jar gitblit.jar --userService c:\myrealm.properties --storePassword something
80     
81 ## Gitblit Configuration
dd7961 82
JM 83 ### Administering Repositories
00afd7 84 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.
dd7961 85
JM 86 All repository settings are stored within the repository `.git/config` file under the *gitblit* section.
87
88     [gitblit]
89         description = master repository
00afd7 90         owner = james
dd7961 91         useTickets = false
JM 92         useDocs = true
93         showRemoteBranches = false
94         accessRestriction = clone
00afd7 95         isFrozen = false
a1ea87 96         showReadme = false
dd7961 97         
JM 98 #### Repository Names
a3bde6 99 Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS.  The name must be composed of letters, digits, or `/ _ - .`<br/>
dd7961 100 Whitespace is illegal.
JM 101
168566 102 Repositories can be grouped within subfolders.  e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*
a3bde6 103
85c2e6 104 All repositories created with Gitblit are *bare* and will automatically have *.git* appended to the name at creation time, if not already specified. 
a3bde6 105
00afd7 106 #### Repository Owner
JM 107 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.
108
dd7961 109 ### Administering Users
00afd7 110 All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`.<br/>
dd7961 111 The format of `users.properties` follows Jetty's convention for HashRealms:
JM 112
113     username,password,role1,role2,role3...
114
115 #### Usernames
116 Usernames must be unique and are case-insensitive.<br/>
117 Whitespace is illegal.
118
119 #### Passwords
56c549 120 User passwords are CASE-SENSITIVE and may be *plain* or *md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).
dd7961 121
JM 122 #### User Roles
f13c4c 123 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.
dd7961 124
85c2e6 125 ## Authentication and Authorization Customization
JM 126 Instead of maintaining a `users.properties` file, you may want to integrate Gitblit into an existing environment.
dd7961 127
85c2e6 128 You may use your own custom *com.gitblit.IUserService* implementation by specifying its fully qualified classname in the *realm.userService* setting.<br/>
dd7961 129
85c2e6 130 Your user service class must be on Gitblit's classpath and must have a public default constructor. 
dd7961 131
1f9dae 132 ## Client Setup and Configuration
JM 133 ### Https with Self-Signed Certificates
d39680 134 You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
1f9dae 135
d39680 136 **NOTE:**<br/>
JM 137 The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.<br/>
138 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/>
139 You must do this because Eclipse/EGit/JGit (<= 1.0.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. 
140  
141 - Eclipse/EGit/JGit
1f9dae 142     1. Window->Preferences->Team->Git->Configuration
JM 143     2. Click the *New Entry* button
144     3. <pre>Key = *http.sslVerify*       
145        Value = *false*</pre>
146 - Command-line Git ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
c22722 147     <pre>git config --global --bool --add http.sslVerify false</pre>
1f9dae 148
JM 149 ### Cloning an Access Restricted Repository 
d39680 150 - Eclipse/EGit/JGit<br/>Nothing special to configure, EGit figures out everything.
1f9dae 151     <pre>https://yourserver/git/your/repository</pre>
JM 152 - Command-line Git<br/>*My testing indicates that your username must be embedded in the url.  YMMV.*
153     <pre>https://username@yourserver/git/your/repository</pre>
154