James Moger
2011-09-28 63ee41d91854e1cf06d8d5cda30cdf7d8d38f3c5
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)
831469 23     - *server.httpPort* and *server.httpsPort*
00afd7 24     - *server.httpBindInterface* and *server.httpsBindInterface*<br/>
831469 25     **https** is strongly recommended because passwords are insecurely transmitted form your browser/git client using Basic authentication!
dd7961 26 3. Execute `gitblit.cmd` or `java -jar gitblit.jar` from a command-line
d39680 27 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*.
230632 28 5. Open your browser to <http://localhost:8080> or <https://localhost:8443> depending on your chosen configuration.
dd7961 29 6. Click the *Login* link and enter the default administrator credentials: **admin / admin**<br/>
d39680 30     **NOTE:** Make sure to change the administrator username and/or password!! 
85c2e6 31
JM 32 ### Creating your own Self-Signed Certificate
d39680 33 Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.
85c2e6 34
9b72a2 35 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.
d39680 36
JM 37 The EGit failure message is something like:
38
39     Cannot get remote repository refs.
40     Reason: https:/myserver.com/git/myrepo.git: cannot open git-upload-pack
41
42 If you want to serve your repositories to another machine over https then you will want to generate your own certificate.
43
44 1. Review the contents of `makekeystore.cmd` or `makekeystore_jdk.cmd`
45 2. Set *your hostname* into the *HOSTNAME* variable.
46 3. Execute the script.<br/>This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*.
85c2e6 47  
d39680 48 **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 49
50 Additionally, if you want to change the value of *server.storePassword* (recommended) you will have to generate a new certificate afterwards.
85c2e6 51
JM 52 ### Running as a Windows Service
d39680 53 Gitblit uses [Apache Commons Daemon](http://commons.apache.org/daemon) to install and configure its Windows service.
JM 54
55 1. Review the contents of the `installService.cmd`
56 2. Set the *ARCH* value as appropriate for your installed Java Virtual Machine.<br/>
57 3. Add any necessary *--StartParams* as enumerated below in **Command-Line Parameters**.
58 4. Execute the script.
59
60 After service installation you can use the `gitblitw.exe` utility to control and modify the runtime settings of the service.<br/>
61 Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html).
62
63 **NOTE:**<br/>
64 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 65
1c9219 66 #### VM Considerations
JM 67 By default, the service installation script configures your Windows service to use your default JVM.  This setup usually defaults to a client VM.<br/>
68 If you have installed a JDK, you might consider using the `gitblitw.exe` utility to manually specify the *server* VM.
69
70 1. Execute `gitblitw.exe`
71 2. On the *Java* tab uncheck *Use default*.
72 3. Manually navigate your filesystem and specify the server VM with the `...` button<br/><pre>
73     Java Virtual Machine:
74     C:\Program Files\Java\jre6\bin\server\jvm.dll</pre>
75
85c2e6 76 #### Command-Line Parameters
JM 77 Command-Line parameters override the values in `gitblit.properties` at runtime.
78
79     --repositoriesFolder   Git Repositories Folder
80     --userService          Authentication and Authorization Service (filename or fully qualified classname)
81     --useNio               Use NIO Connector else use Socket Connector.
82     --httpPort             HTTP port for to serve. (port <= 0 will disable this connector)
83     --httpsPort            HTTPS port to serve.  (port <= 0 will disable this connector)
84     --storePassword        Password for SSL (https) keystore.
85     --shutdownPort         Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor)
86     --tempFolder           Folder for server to extract built-in webapp
87     
88 **Example**
89
90     java -jar gitblit.jar --userService c:\myrealm.properties --storePassword something
790c38 91
JM 92 ## Upgrading Gitblit
93 Generally, upgrading is easy.
94
95 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.
96
97 Any important changes to the setting keys or default values will always be mentioned in the [release log](releases.html).
98
99 ### Upgrading Gitblit WAR
100 1. Backup your `web.xml` file
101 2. Delete currently deployed gitblit WAR
102 3. Deploy new WAR and overwrite the `web.xml` file with your backup
103 4. Review and optionally apply any new settings as indicated in the [release log](releases.html). 
104  
105 ### Upgrading Gitblit GO
106  
107 1. Backup your `gitblit.properties` file
108 2. Backup your `users.properties` file *(if it is located in the Gitblit GO folder)*
109 3. Unzip Gitblit GO to a new folder
110 4. Overwrite the `gitblit.properties` file with your backup
111 5. Overwrite the `users.properties` file with your backup *(if it was located in the Gitblit GO folder)*
112 6. Review and optionally apply any new settings as indicated in the [release log](releases.html).
113
114 #### Upgrading Windows Service
115 You may need to delete your old service definition and install a new one depending on what has changed in the release.  
85c2e6 116     
JM 117 ## Gitblit Configuration
dd7961 118
JM 119 ### Administering Repositories
00afd7 120 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 121
JM 122 All repository settings are stored within the repository `.git/config` file under the *gitblit* section.
123
124     [gitblit]
125         description = master repository
00afd7 126         owner = james
dd7961 127         useTickets = false
JM 128         useDocs = true
129         showRemoteBranches = false
130         accessRestriction = clone
00afd7 131         isFrozen = false
a1ea87 132         showReadme = false
f6740d 133         federationStrategy = FEDERATE_THIS
831469 134         isFederated = false
8f73a7 135         federationSets = 
dd7961 136         
JM 137 #### Repository Names
a3bde6 138 Repository names must be unique and are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS.  The name must be composed of letters, digits, or `/ _ - .`<br/>
dd7961 139 Whitespace is illegal.
JM 140
168566 141 Repositories can be grouped within subfolders.  e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*
a3bde6 142
85c2e6 143 All repositories created with Gitblit are *bare* and will automatically have *.git* appended to the name at creation time, if not already specified. 
a3bde6 144
00afd7 145 #### Repository Owner
JM 146 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.
147
dd7961 148 ### Administering Users
00afd7 149 All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`.<br/>
dd7961 150 The format of `users.properties` follows Jetty's convention for HashRealms:
JM 151
152     username,password,role1,role2,role3...
153
154 #### Usernames
155 Usernames must be unique and are case-insensitive.<br/>
156 Whitespace is illegal.
157
158 #### Passwords
56c549 159 User passwords are CASE-SENSITIVE and may be *plain* or *md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*).
dd7961 160
JM 161 #### User Roles
831469 162 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.
dd7961 163
85c2e6 164 ## Authentication and Authorization Customization
JM 165 Instead of maintaining a `users.properties` file, you may want to integrate Gitblit into an existing environment.
dd7961 166
85c2e6 167 You may use your own custom *com.gitblit.IUserService* implementation by specifying its fully qualified classname in the *realm.userService* setting.<br/>
dd7961 168
85c2e6 169 Your user service class must be on Gitblit's classpath and must have a public default constructor. 
dd7961 170
230632 171 %BEGINCODE%
JM 172 public interface IUserService {
173
174     /**
63ee41 175      * Setup the user service.
JM 176      * 
177      * @param settings
178      * @since 0.6.1
179      */
180     @Override
181     public void setup(IStoredSettings settings) {
182     }
183     
184     /**
230632 185      * Does the user service support cookie authentication?
JM 186      * 
187      * @return true or false
188      */
189     boolean supportsCookies();
190
191     /**
192      * Returns the cookie value for the specified user.
193      * 
194      * @param model
195      * @return cookie value
196      */
197     char[] getCookie(UserModel model);
198
199     /**
200      * Authenticate a user based on their cookie.
201      * 
202      * @param cookie
203      * @return a user object or null
204      */
205     UserModel authenticate(char[] cookie);
206
207     /**
208      * Authenticate a user based on a username and password.
209      * 
210      * @param username
211      * @param password
212      * @return a user object or null
213      */
214     UserModel authenticate(String username, char[] password);
215
216     /**
217      * Retrieve the user object for the specified username.
218      * 
219      * @param username
220      * @return a user object or null
221      */
222     UserModel getUserModel(String username);
223
224     /**
225      * Updates/writes a complete user object.
226      * 
227      * @param model
228      * @return true if update is successful
229      */
230     boolean updateUserModel(UserModel model);
231
232     /**
233      * Adds/updates a user object keyed by username. This method allows for
234      * renaming a user.
235      * 
236      * @param username
237      *            the old username
238      * @param model
239      *            the user object to use for username
240      * @return true if update is successful
241      */
242     boolean updateUserModel(String username, UserModel model);
243
244     /**
245      * Deletes the user object from the user service.
246      * 
247      * @param model
248      * @return true if successful
249      */
250     boolean deleteUserModel(UserModel model);
251
252     /**
253      * Delete the user object with the specified username
254      * 
255      * @param username
256      * @return true if successful
257      */
258     boolean deleteUser(String username);
259
260     /**
261      * Returns the list of all users available to the login service.
262      * 
263      * @return list of all usernames
264      */
265     List<String> getAllUsernames();
266
267     /**
268      * Returns the list of all users who are allowed to bypass the access
269      * restriction placed on the specified repository.
270      * 
271      * @param role
272      *            the repository name
273      * @return list of all usernames that can bypass the access restriction
274      */
275     List<String> getUsernamesForRepositoryRole(String role);
276
277     /**
278      * Sets the list of all uses who are allowed to bypass the access
279      * restriction placed on the specified repository.
280      * 
281      * @param role
282      *            the repository name
283      * @param usernames
284      * @return true if successful
285      */
286     boolean setUsernamesForRepositoryRole(String role, List<String> usernames);
287
288     /**
289      * Renames a repository role.
290      * 
291      * @param oldRole
292      * @param newRole
293      * @return true if successful
294      */
295     boolean renameRepositoryRole(String oldRole, String newRole);
296
297     /**
298      * Removes a repository role from all users.
299      * 
300      * @param role
301      * @return true if successful
302      */
303     boolean deleteRepositoryRole(String role);
304
305     /**
306      * @See java.lang.Object.toString();
307      * @return string representation of the login service
308      */
309     String toString();
310 }
311 %ENDCODE%
312
1f9dae 313 ## Client Setup and Configuration
JM 314 ### Https with Self-Signed Certificates
d39680 315 You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
1f9dae 316
d39680 317 **NOTE:**<br/>
JM 318 The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.<br/>
319 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/>
9b72a2 320 You must do this because Eclipse/EGit/JGit (<= 1.1.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting. 
d39680 321  
JM 322 - Eclipse/EGit/JGit
1f9dae 323     1. Window->Preferences->Team->Git->Configuration
JM 324     2. Click the *New Entry* button
325     3. <pre>Key = *http.sslVerify*       
326        Value = *false*</pre>
327 - Command-line Git ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
c22722 328     <pre>git config --global --bool --add http.sslVerify false</pre>
1f9dae 329
JM 330 ### Cloning an Access Restricted Repository 
d39680 331 - Eclipse/EGit/JGit<br/>Nothing special to configure, EGit figures out everything.
1f9dae 332     <pre>https://yourserver/git/your/repository</pre>
JM 333 - Command-line Git<br/>*My testing indicates that your username must be embedded in the url.  YMMV.*
334     <pre>https://username@yourserver/git/your/repository</pre>
335