1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
## 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.
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.<br/>
Open `web.xml` in your favorite text editor and make sure to review and set:
- <context-parameter> *git.repositoryFolder* (set the full path to your repositories folder)
- <context-parameter> *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!!
## Gitblit GO Setup
1. Download and unzip [Gitblit GO %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%GO%).<br/>
*Its best to eliminate spaces in the path name.*
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:
- *git.repositoryFolder* (path may be relative or absolute)
- *server.tempFolder* (path may be relative or absolute)
- *server.httpBindInterface* and *server.httpsBindInterface*<br/>
**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 *localhost* certificate is generated.<br/>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> 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!!
### Creating your own Self-Signed Certificate
Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.
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.
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*.
**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!
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
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.<br/>
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.
--repositoriesFolder Git Repositories Folder
--userService Authentication and Authorization Service (filename or fully qualified classname)
--useNio Use NIO Connector else use Socket Connector.
--httpPort HTTP port for to serve. (port <= 0 will disable this connector)
--httpsPort HTTPS port to serve. (port <= 0 will disable this connector)
--storePassword Password for SSL (https) keystore.
--shutdownPort Port for Shutdown Monitor to listen on. (port <= 0 will disable this monitor)
--tempFolder Folder for server to extract built-in webapp
**Example**
java -jar gitblit.jar --userService c:\myrealm.properties --storePassword something
## Gitblit Configuration
### Administering Repositories
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.
All repository settings are stored within the repository `.git/config` file under the *gitblit* section.
[gitblit]
description = master repository
owner = james
useTickets = false
useDocs = true
showRemoteBranches = false
accessRestriction = clone
isFrozen = false
showReadme = false
#### 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.
Repositories can be grouped within subfolders. e.g. *libraries/mycoollib.git* and *libraries/myotherlib.git*
All repositories created with Gitblit are *bare* and 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.
### Administering Users
All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`.<br/>
The format of `users.properties` follows Jetty's convention for HashRealms:
username,password,role1,role2,role3...
#### Usernames
Usernames must be unique and are case-insensitive.<br/>
Whitespace is illegal.
#### Passwords
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 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.
## 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/>
Your user service class must be on Gitblit's classpath and must have a public default constructor.
## Client Setup and Configuration
### Https with Self-Signed Certificates
You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
**NOTE:**<br/>
The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.<br/>
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/>
You must do this because Eclipse/EGit/JGit (<= 1.0.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>
### Cloning an Access Restricted Repository
- Eclipse/EGit/JGit<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>
|
