Skip to content

Commit 8c99a79

Browse files
gitblitgitblit
committed
Documentation
1 parent 5c5b7a8 commit 8c99a79

File tree

12 files changed

+605
-605
lines changed

12 files changed

+605
-605
lines changed

‎build.xml‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -672,8 +672,21 @@
672672
<page name="features" src="features.mkd" />
673673
<page name="screenshots" src="screenshots.mkd" />
674674
</menu>
675-
<menu name="documentation">
676-
<page name="setup" src="setup.mkd" />
675+
<menu name="documentation" pager="true" pagerPlacement="bottom" pagerLayout="justified">
676+
<page name="setup GO" src="setup_go.mkd" />
677+
<page name="upgrade GO" src="upgrade_go.mkd" />
678+
<divider />
679+
<page name="setup WAR" src="setup_war.mkd" />
680+
<page name="upgrade WAR" src="upgrade_war.mkd" />
681+
<divider />
682+
<page name="administration" src="setup.mkd" />
683+
<page name="authentication" src="setup_authentication.mkd" />
684+
<page name="push hooks" src="setup_hooks.mkd" />
685+
<page name="lucene indexing" src="setup_lucene.mkd" />
686+
<page name="reverse proxies" src="setup_proxy.mkd" />
687+
<divider />
688+
<page name="git client setup" src="setup_client.mkd" />
689+
<divider />
677690
<page name="federation" src="federation.mkd" />
678691
<divider />
679692
<page name="settings" src="properties.mkd" />

‎src/site/design.mkd‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,6 @@ The following dependencies are automatically downloaded by Gitblit GO (or alread
5555
### Other Build Dependencies
5656
- [Fancybox image viewer](http://fancybox.net) (MIT and GPL dual-licensed)
5757
- [JUnit](http://junit.org) (Common Public License)
58-
- [commons-net](http://commons.apache.org/net) (Apache 2.0)
59-
- [ant-googlecode](http://code.google.com/p/ant-googlecode) (New BSD)
6058
- [Moxie](http://moxie.gitblit.com) (Apache 2.0)
6159

6260
## Building from Source
@@ -72,10 +70,7 @@ Additionally, [Google CodePro AnalytiX](http://code.google.com/javadevtools), [e
7270
4. Select your gitblit project root and **Refresh** the project, this should correct all build problems.
7371
5. Using JUnit, execute the `com.gitblit.tests.GitBlitSuite` test suite.
7472
*This will clone some repositories from the web and run through the unit tests.*
75-
5. Review the settings in `gitblit.properties` in your project root.
76-
- By default, the *git.repositoriesFolder* points to the repositories cloned by the test suite.
77-
- If running on Linux you may have to change the served port(s) to > 1024 unless you are developing as the root user.
78-
6. Execute the *com.gitblit.Launcher* class to start Gitblit.
73+
6. Execute the *com.gitblit.GitBlitServer* class to start Gitblit.
7974

8075

8176
## Contributing

‎src/site/setup.mkd‎

Lines changed: 11 additions & 597 deletions
Large diffs are not rendered by default.

‎src/site/setup_authentication.mkd‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
## Built-in Authentication
2+
3+
By default, Gitblit stores and authenticates all users against `users.conf`. However, you may wish to integrate Gitblit into an existing user account infrastructure.
4+
5+
Gitblit supports additional authentication mechanisms aside from it's internal one.
6+
7+
* LDAP authentication
8+
* Windows authentication
9+
* Redmine auhentication
10+
* Salesforce.com authentication
11+
12+
### LDAP Authentication
13+
*SINCE 1.0.0*
14+
15+
LDAP can be used to authenticate Users and optionally control Team memberships. When properly configured, Gitblit will delegate authentication to your LDAP server and will cache some user information in the usual users file (.conf or .properties).
16+
17+
When using the LDAP User Service, new user accounts can not be manually created from Gitblit. Gitblit user accounts are automatically created for new users on their first succesful authentication through Gitblit against the LDAP server. It is also important to note that the LDAP User Service does not retrieve or store user passwords nor does it implement any LDAP-write functionality.
18+
19+
To use the *LdapUserService* set *realm.userService=com.gitblit.LdapUserService* in your `gitblit.properties` file or your `web.xml` file and then configure the *realm.ldap* settings appropriately for your LDAP environment.
20+
21+
#### Example LDAP Layout
22+
![block diagram](ldapSample.png "LDAP Sample")
23+
24+
Please see [ldapUserServiceSampleData.ldif](https://github.com/gitblit/gitblit/blob/master/tests/com/gitblit/tests/resources/ldapUserServiceSampleData.ldif) to see the data in LDAP that reflects the above picture.
25+
26+
#### Gitblit Settings for Example LDAP Layout
27+
The following are the settings required to configure Gitblit to authenticate against the example LDAP server with LDAP-controlled team memberships.
28+
29+
<table class="table">
30+
<thead>
31+
<tr><th>parameter</th><th>value</th><th>description</th></tr>
32+
</thead>
33+
<tbody>
34+
<tr>
35+
<th>realm.ldap.server</th><td>ldap://localhost:389</td>
36+
<td>Tells Gitblit to connect to the LDAP server on localhost port 389. The URL Must be of form ldap(s)://&lt;server&gt;:&lt;port&gt; with port being optional (389 for ldap, 636 for ldaps).</td>
37+
</tr>
38+
<tr>
39+
<th>realm.ldap.username</th><td>cn=Directory Manager</td>
40+
<td>The credentials that will log into the LDAP server</td>
41+
</tr>
42+
<tr>
43+
<th>realm.ldap.password</th><td>password</td>
44+
<td>The credentials that will log into the LDAP server</td>
45+
</tr>
46+
<tr>
47+
<th>realm.ldap.backingUserService</th><td>users.conf</td>
48+
<td>Where to store all information that is used by Gitblit. All information will be synced here upon user login.</td>
49+
</tr>
50+
<tr>
51+
<th>realm.ldap.maintainTeams</th><td>true</td>
52+
<td>Are team memberships maintained in LDAP (<em>true</em>) or manually in Gitblit (<em>false</em>).</td>
53+
</tr>
54+
<tr>
55+
<th>realm.ldap.accountBase</th><td>OU=Users,OU=UserControl,OU=MyOrganization,DC=MyDomain</td>
56+
<td>What is the root node for all users in this LDAP system. Subtree searches will start from this node.</td>
57+
</tr>
58+
<tr>
59+
<th>realm.ldap.accountPattern</th><td>(&(objectClass=person)(sAMAccountName=${username}))</td><td>The LDAP search filter that will match a particular user in LDAP. ${username} will be replaced with whatever the user enters as their username in the Gitblit login panel.</td>
60+
</tr>
61+
<tr>
62+
<th>realm.ldap.groupBase</th><td>OU=Groups,OU=UserControl,OU=MyOrganization,DC=MyDomain</td>
63+
<td>What is the root node for all teams in this LDAP system. Subtree searches will start from this node.</td>
64+
</tr>
65+
<tr>
66+
<th>realm.ldap.groupMemberPattern</th><td>(&(objectClass=group)(member=${dn}))</td><td>The LDAP search filter that will match all teams for the authenticating user. ${username} will be replaced with whatever the user enters as their username in the Gitblit login panel. Anything else in ${} will be replaced by Attributes from the User node.</td>
67+
</tr>
68+
<tr>
69+
<th>realm.ldap.admins</th><td>@Git_Admins</td><td>A space-delimited list of usernames and/or teams that indicate admin status in Gitblit. Teams are referenced with a leading <em>@</em> character.</td>
70+
</tr>
71+
</tbody>
72+
</table>
73+
74+
#### LDAP In-Memory Server
75+
76+
You can start Gitblit GO with an in-memory LDAP server by specifying the *--ldapLdifFile* command-line argument. The LDAP server will listen on localhost of the port specified in *realm.ldap.url* of `gitblit.properties`. Additionally, a root user record is automatically created for *realm.ldap.username* and *realm.ldap.password*. Please note that the ldaps:// protocol is not supported for the in-memory server.
77+
78+
### Windows Authentication
79+
80+
### Redmine Authentication
81+
82+
### Salesforce.com Authentication
83+
84+
## Custom Authentication
85+
This is the simplest choice where you implement custom authentication and delegate all other standard user and team operations to one of Gitblit's user service implementations. This choice insulates your customization from changes in User and Team model classes and additional API that may be added to IUserService.
86+
87+
Please subclass [com.gitblit.GitblitUserService](https://github.com/gitblit/gitblit/blob/master/src/com/gitblit/GitblitUserService.java) and override the *setup()* and *authenticate()* methods.
88+
Make sure to set the *serviceImpl* field in your *setup()* method.
89+
90+
You may use your subclass by specifying its fully qualified classname in the *realm.userService* setting.
91+
92+
Your subclass must be on Gitblit's classpath and must have a public default constructor.
93+
94+
### Custom Everything
95+
Instead of maintaining a `users.conf` or `users.properties` file, you may want to integrate Gitblit into an existing environment.
96+
97+
You may use your own custom *com.gitblit.IUserService* implementation by specifying its fully qualified classname in the *realm.userService* setting.
98+
99+
Your user service class must be on Gitblit's classpath and must have a public default constructor.
100+
Please see the following interface definition [com.gitblit.IUserService](https://github.com/gitblit/gitblit/blob/master/src/com/gitblit/IUserService.java).
101+

‎src/site/setup_client.mkd‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
2+
## Client Setup and Configuration
3+
### Https with Self-Signed Certificates
4+
You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
5+
6+
**NOTE:**
7+
The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.
8+
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.
9+
You must do this because Eclipse/EGit/JGit (< 3.0) always verifies certificate hostnames, regardless of the *http.sslVerify=false* client-side setting.
10+
11+
- **Eclipse/EGit/JGit**
12+
1. Window->Preferences->Team->Git->Configuration
13+
2. Click the *New Entry* button
14+
3. <pre>Key = <em>http.sslVerify</em>
15+
Value = <em>false</em></pre>
16+
- **Command-line Git** ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
17+
<pre>git config --global --bool --add http.sslVerify false</pre>
18+
19+
### Http Post Buffer Size
20+
You may find the default post buffer of your git client is too small to push large deltas to Gitblit. Sometimes this can be observed on your client as *hanging* during a push. Other times it can be observed by git erroring out with a message like: error: RPC failed; result=52, HTTP code = 0.
21+
22+
This can be adjusted on your client by changing the default post buffer size:
23+
<pre>git config --global http.postBuffer 524288000</pre>
24+
25+
### Disabling SNI
26+
27+
You may run into SNI alerts (Server Name Indication). These will manifest as failures to clone or push to your Gitblit instance.
28+
29+
#### Java-based Clients
30+
31+
When using Java 7-based clients, SNI is enabled by default. You can disable SNI by specifying the JVM system parameter `-Djsse.enableSNIExtension=false` when your Java-based client launches.
32+
33+
For Eclipse, you can append `-Djsse.enableSNIExtension=false` to your *eclipse.ini* file.
34+
35+
#### Native Clients
36+
37+
Native clients may display an error when attempting to clone or push that looks like this:
38+
---FIXED---
39+
C:\projects\git\gitblit>git push rhcloud master
40+
error: error:14077458:SSL routines:SSL23_GET_SERVER_HELLO:reason(1112) while accessing https://demo-gitblit.rhcloud.com/git/gitblit.git/info/refs?service=git-receive-pack
41+
fatal: HTTP request failed
42+
---FIXED---
43+
44+
### Cloning a Repository
45+
46+
Gitblit provides many custom clone links for popular Git clients on the Summary page of each repository. If you have one or more of those clients installed, you should be able to click the link to initiate cloning with the selected tool.

0 commit comments

Comments
 (0)