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 |
- <context-parameter> *git.repositoryFolder* (set the full path to your repositories folder)
|
|
9 |
- <context-parameter> *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 |
|