From cc04772888848c754880ed181fcf13c0a658e7ed Mon Sep 17 00:00:00 2001 From: James Moger Date: Sat, 13 Jul 2013 10:32:52 -0400 Subject: Documentation --- build.xml | 39 ++++++-- src/site/administration.mkd | 200 ++++++++++++++++++++++++++++++++++++++ src/site/faq.mkd | 10 +- src/site/roadmap.mkd | 31 ++---- src/site/setup.mkd | 200 -------------------------------------- src/site/setup_authentication.mkd | 30 +++++- src/site/setup_proxy.mkd | 24 +++++ src/site/setup_viewer.mkd | 47 +++++++++ 8 files changed, 345 insertions(+), 236 deletions(-) create mode 100644 src/site/administration.mkd delete mode 100644 src/site/setup.mkd create mode 100644 src/site/setup_viewer.mkd diff --git a/build.xml b/build.xml index cc58f603..8910c3c3 100644 --- a/build.xml +++ b/build.xml @@ -673,18 +673,24 @@ - - + + + + - - + + + + - + + + @@ -923,11 +929,30 @@ - + + + + + + + + + + + + + + + + + + + + - + diff --git a/src/site/administration.mkd b/src/site/administration.mkd new file mode 100644 index 00000000..7ed40ebe --- /dev/null +++ b/src/site/administration.mkd @@ -0,0 +1,200 @@ +## 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 + federationStrategy = FEDERATE_THIS + isFederated = false + skipSizeCalculation = false + federationSets = + +#### Repository Names +Repository names must be case-insensitive-unique but are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - . ~`
+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. + +### Access Restrictions and Access Permissions +![permissions matrix](permissions_matrix.png "Permissions and Restrictions") + +#### Discrete Permissions (Gitblit v1.2.0+) + +Since v1.2.0, Gitblit supports more discrete permissions. While Gitblit does not offer a built-in solution for branch-based permissions like Gitolite, it does allow for the following repository access permissions: + +- **V** (view in web ui, RSS feeds, download zip) +- **R** (clone) +- **RW** (clone and push) +- **RWC** (clone and push with ref creation) +- **RWD** (clone and push with ref creation, deletion) +- **RW+** (clone and push with ref creation, deletion, rewind) + +These permission codes are combined with the repository path to create a user permission: + + RW:mygroup/myrepo.git + +**NOTE:** +The following repository permissions are equivalent: + +- myrepo.git +- RW+:myrepo.git + +This is to preserve backwards-compatibility with Gitblit <= 1.1.0 which granted rewind power to all access-permitted users. + +#### Discrete Permissions with Regex Matching (Gitblit v1.2.0+) + +Gitblit also supports *case-insensitive* regex matching for repository permissions. The following permission grants push privileges to all repositories in the *mygroup* folder. + + RW:mygroup/.* + +##### Exclusions + +When using regex matching it may also be useful to exclude specific repositories or to exclude regex repository matches. You may specify the **X** permission for exclusion. The following example grants clone permission to all repositories except the repositories in mygroup. The user/team will have no access whatsoever to these repositories. + + X:mygroup/.* + R:.* + +##### Order is Important + +The preceding example should suggest that order of permissions is important with regex matching. Here are the rules for determining the permission that is applied to a repository request: + +1. If the user is an admin or repository owner, then RW+ +2. Else if user has an explicit permission, use that +3. Else check for the first regex match in user permissions +4. Else check for the HIGHEST permission from team memberships + 1. If the team is an admin team, then RW+ + 2. Else if a team has an explicit permission, use that + 3. Else check for the first regex match in team permissions + +#### No-So-Discrete Permissions (Gitblit <= v1.1.0) + +Prior to v1.2.0, Gitblit has two main access permission groupings: + +1. what you are permitted to do as an anonymous user +2. **RW+** for any permitted user + +#### Committer Verification + +You may optionally enable committer verification which requires that each commit be committed by the authenticated user pushing the commits. i.e. If Bob is pushing the commits, Bob **must** be the committer of those commits. + +**How is this enforced?** + +Bob must set his *user.name* and *user.email* values for the repository to match his Gitblit user account **BEFORE** committing to his repository. +
+[user "bob"]
+    displayName = Bob Jones
+    emailAddress = bob@somewhere.com
+
+
+    git config user.name "Bob Jones"
+    git config user.email bob@somewhere.com	
+
+or + + git config user.name bob + git config user.email bob@somewhere.com + +If the Gitblit account does not specify an email address, then the committer email address is ignored. However, if the account does specify an address it must match the committer's email address. Display name or username can be used as the committer name. + +All checks are case-insensitive. + +**What about merges?** + +You can not use fast-forward merges on your client when using committer verification. You must specify *--no-ff* to ensure that a merge commit is created with your identity as the committer. Only the first/left parent chain is traversed when verifying commits. + +#### Reflog + +Gitblit v1.2.1 introduced an incomplete reflog mechanism which was completed in 1.3.0. All pushes to Gitblit are automatically logged on an orphan branch, refs/gitblit/reflog. If this ref exists, the reflog page link will be displayed on the repository pages. + +This reflog is similar to, but not the same as, the normal Git reflog. The Gitblit reflog links Gitblit accounts to ref changes and because it is stored on an orphan branch, the reflog is portable by the federation mechanism or by a normal git clone --mirror command. + +### Teams + +Teams have assigned users and assigned repositories. A user can be a member of multiple teams and a repository may belong to multiple teams. This allows the administrator to quickly add a user to a team without having to keep track of all the appropriate repositories. + +### Administering Users +All users and permissions are stored in the `users.conf` file. Your file extension must be *.conf* in order to use this user service. + +The `users.conf` file uses a Git-style configuration format: + + [user "admin"] + password = admin + role = "#admin" + role = "#notfederated" + repository = RW+:repo1.git + repository = RW+:repo2.git + + [user "hannibal"] + password = bossman + repository = RWD:topsecret.git + repository = RW+:ateam/[A-Za-z0-9-~_\\./]+ + + [user "faceman"] + password = vanity + + [user "murdock"] + password = crazy + + [user "babaracus"] + password = grrrr + + [team "ateam"] + user = hannibal + user = faceman + user = murdock + user = babaracus + repository = RW:topsecret.git + mailingList = list@ateam.org + postReceiveScript = sendmail + +The `users.conf` file allows flexibility for adding new fields to a UserModel object without imposing the complexity of relying on an embedded SQL database. + +### Usernames +Usernames must be unique and are case-insensitive. +Whitespace is illegal. + +### Passwords +User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*). + +### User Roles +There are four actual *roles* in Gitblit: + +- *#admin*, which grants administrative powers to that user for all repositories, users, and teams +- *#notfederated*, which prevents an account from being pulled by another Gitblit instance +- *#create*, which allows the user the power to create personal repositories +- *#fork*, which allows the user to create a personal fork of an existing Gitblit-hosted repository + +### Personal Repositories & Forks + +Personal Repositories and Forks are related but are controlled individually. + +#### Creating a Personal Repository +A user may be granted the power to create personal repositories by specifying the *#create* role through the web ui or through the RPC mechanism via the Gitblit Manager. Personal repositories are exactly like common/shared repositories except that the owner has a few additional administrative powers for that repository, like rename and delete. + +#### Creating a Fork +A user may also be granted the power to fork an existing repository hosted on your Gitblit server to their own personal clone by specifying the *#fork* role through the web ui or via the Gitblit Manager. + +Forks are mostly likely personal repositories or common/shared repositories except for two important differences: + +1. Forks inherit a view/clone access list from the origin repository. +i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork. This is to facilitate collaboration. +2. Forks are always listed in the fork network, regardless of any access restriction set on the fork. +In other words, if you fork *RepoA.git* to *~me/RepoA.git* and then set the access restriction of *~me/RepoA.git* to *Authenticated View, Clone, & Push* your fork will still be listed in the fork network for *RepoA.git*. + +If you really must have an invisible fork, the clone it locally, create a new personal repository for your invisible fork, and push it back to that personal repository. + diff --git a/src/site/faq.mkd b/src/site/faq.mkd index 84a0a817..bf8055d3 100644 --- a/src/site/faq.mkd +++ b/src/site/faq.mkd @@ -21,7 +21,7 @@ Value = false This is a long-standing, known bug in the native Git for Windows implementation. -https://groups.google.com/d/topic/msysgit/at8D7J-h7mw/discussion +Please see [this thread](https://groups.google.com/d/topic/msysgit/at8D7J-h7mw/discussion) for details. ### Why can't I access Gitblit GO from another machine? 1. Please check *server.httpBindInterface* and *server.httpsBindInterface* in `gitblit.properties`, you may be only be serving on *localhost*. @@ -41,7 +41,7 @@ Run the server as *root* (security concern) or change the ports you are serving 2. Confirm that the servlet container process has full read-write-execute permissions to your *git.repositoriesFolder*. ### Gitblit WAR will not authenticate any users?! -Confirm that the <context-param> *realm.userService* value in your `web.xml` file actually points to a `users.conf` or `users.properties` file. +Confirm that the <context-param> *realm.userService* value in your `web.xml` file actually points to a `users.conf` file. ### Gitblit won't open my grouped repository (/group/myrepo.git) or browse my log/branch/tag/ref?! This is likely an url encoding/decoding problem with forward slashes: @@ -125,9 +125,9 @@ Yes. Gitblit will run just fine with a JRE. Gitblit can optionally use `keytool` from the JDK to generate self-signed certificates, but normally Gitblit uses [BouncyCastle][bouncycastle] for that need. ### Does Gitblit use a database to store its data? -No. Gitblit stores its repository configuration information within the `.git/config` file and its user information in `users.conf`, `users.properties`, or whatever filename is configured in `gitblit.properties`. +No. Gitblit stores its repository configuration information within the `.git/config` file and its user information in `users.conf` or whatever filename is configured in `gitblit.properties`. -### Can I manually edit users.conf, users.properties, gitblit.properties, or .git/config? +### Can I manually edit users.conf, gitblit.properties, or .git/config? Yes. You can manually manipulate all of them and (most) changes will be immediately available to Gitblit.
Exceptions to this are noted in `gitblit.properties`. **NOTE:** @@ -176,4 +176,4 @@ Yes. Most messages are localized to a standard Java properties file. [jgit]: http://eclipse.org/jgit "Eclipse JGit Site" [git]: http://git-scm.com "Official Git Site" [mina]: http://mina.apache.org "Apache Mina" -[bouncycastle]: http://bouncycastle.org "The Legion of the Bouncy Castle" \ No newline at end of file +[bouncycastle]: http://bouncycastle.org "The Legion of the Bouncy Castle" diff --git a/src/site/roadmap.mkd b/src/site/roadmap.mkd index 509c6b20..8b3e31f0 100644 --- a/src/site/roadmap.mkd +++ b/src/site/roadmap.mkd @@ -1,28 +1,17 @@ ## Roadmap This is not exactly a formal roadmap but it is a priority list of what might be implemented in future releases. -This list is volatile. +This list is volatile and may not reflect what will be in the next release. -### TODO (high priority) - -* Eclipse: create plugin to enumerate repositories and delegate cloning to EGit -* Manager: support federation RPCs -* Manager: redesign ref indicators in log, search, and activity views to support multiple local branches, remote branches, and tags - -### TODO (medium priority) - -* Gitblit: editable settings page in GO/WAR -* Gitblit: Clone Repository feature (issue 5) +* Integrate an SSH daemon to complete the transport trifecta: http/https, git, and ssh +* GitHub-style Pull Requests or Gerrit-style Patchsets (issue 215) +* Clone/Mirror Repository feature (issue 5) * optional scheduled pulls * optional automatic push to origin/remotes? * optional manual push to origin/remotes? -* Gitblit: Repository regex substitutions should be stored in .git/.config, not gitblit.properties - -### IDEAS - -* Gitblit: GitHub-style Pull Requests or Gerrit-style Patchsets -* Gitblit: Re-use the EGit branch visualization table cell renderer as some sort of servlet -* Gitblit: diff should highlight inserted/removed fragment compared to original line -* Gitblit: respect Gerrit branch permissions -* Gitblit: Consider creating more Git model objects and exposing them via the JSON RPC interface to allow inspection/retrieval of Git commits, Git trees, etc from Gitblit. -* Gitblit: Blame coloring by author (issue 2) +* Re-use the EGit branch visualization table cell renderer as some sort of servlet (issue 194) +* Diff should highlight inserted/removed fragment compared to original line +* Respect Gerrit branch permissions, if found (issue 36) +* Repository regex substitutions should be stored in .git/.config, not gitblit.properties +* Editable settings page in GO/WAR +* Create Eclipse plugin to enumerate repositories and delegate cloning to EGit diff --git a/src/site/setup.mkd b/src/site/setup.mkd deleted file mode 100644 index 770e97b3..00000000 --- a/src/site/setup.mkd +++ /dev/null @@ -1,200 +0,0 @@ -## 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 - federationStrategy = FEDERATE_THIS - isFederated = false - skipSizeCalculation = false - federationSets = - -#### Repository Names -Repository names must be case-insensitive-unique but are CASE-SENSITIVE ON CASE-SENSITIVE FILESYSTEMS. The name must be composed of letters, digits, or `/ _ - . ~`
-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. - -### Access Restrictions and Access Permissions -![permissions matrix](permissions_matrix.png "Permissions and Restrictions") - -#### Discrete Permissions (Gitblit v1.2.0+) - -Since v1.2.0, Gitblit supports more discrete permissions. While Gitblit does not offer a built-in solution for branch-based permissions like Gitolite, it does allow for the following repository access permissions: - -- **V** (view in web ui, RSS feeds, download zip) -- **R** (clone) -- **RW** (clone and push) -- **RWC** (clone and push with ref creation) -- **RWD** (clone and push with ref creation, deletion) -- **RW+** (clone and push with ref creation, deletion, rewind) - -These permission codes are combined with the repository path to create a user permission: - - RW:mygroup/myrepo.git - -#### Discrete Permissions with Regex Matching (Gitblit v1.2.0+) - -Gitblit also supports *case-insensitive* regex matching for repository permissions. The following permission grants push privileges to all repositories in the *mygroup* folder. - - RW:mygroup/.* - -##### Exclusions - -When using regex matching it may also be useful to exclude specific repositories or to exclude regex repository matches. You may specify the **X** permission for exclusion. The following example grants clone permission to all repositories except the repositories in mygroup. The user/team will have no access whatsoever to these repositories. - - X:mygroup/.* - R:.* - -##### Order is Important - -The preceding example should suggest that order of permissions is important with regex matching. Here are the rules for determining the permission that is applied to a repository request: - -1. If the user is an admin or repository owner, then RW+ -2. Else if user has an explicit permission, use that -3. Else check for the first regex match in user permissions -4. Else check for the HIGHEST permission from team memberships - 1. If the team is an admin team, then RW+ - 2. Else if a team has an explicit permission, use that - 3. Else check for the first regex match in team permissions - -#### No-So-Discrete Permissions (Gitblit <= v1.1.0) - -Prior to v1.2.0, Gitblit has two main access permission groupings: - -1. what you are permitted to do as an anonymous user -2. **RW+** for any permitted user - -#### Committer Verification - -You may optionally enable committer verification which requires that each commit be committed by the authenticated user pushing the commits. i.e. If Bob is pushing the commits, Bob **must** be the committer of those commits. - -**How is this enforced?** - -Bob must set his *user.name* and *user.email* values for the repository to match his Gitblit user account **BEFORE** committing to his repository. -
-[user "bob"]
-    displayName = Bob Jones
-    emailAddress = bob@somewhere.com
-
-
-    git config user.name "Bob Jones"
-    git config user.email bob@somewhere.com	
-
-or - - git config user.name bob - git config user.email bob@somewhere.com - -If the Gitblit account does not specify an email address, then the committer email address is ignored. However, if the account does specify an address it must match the committer's email address. Display name or username can be used as the committer name. - -All checks are case-insensitive. - -**What about merges?** - -You can not use fast-forward merges on your client when using committer verification. You must specify *--no-ff* to ensure that a merge commit is created with your identity as the committer. Only the first/left parent chain is traversed when verifying commits. - -#### Reflog - -Gitblit v1.2.1 introduced an incomplete reflog mechanism which was completed in 1.3.0. All pushes to Gitblit are automatically logged on an orphan branch, refs/gitblit/reflog. If this ref exists, the reflog page link will be displayed on the repository pages. - -This reflog is similar to, but not the same as, the normal Git reflog. The Gitblit reflog links Gitblit accounts to ref changes and because it is stored on an orphan branch, the reflog is portable by the federation mechanism or by a normal git clone --mirror command. - -### Teams - -Teams have assigned users and assigned repositories. A user can be a member of multiple teams and a repository may belong to multiple teams. This allows the administrator to quickly add a user to a team without having to keep track of all the appropriate repositories. - -### Administering Users -All users and permissions are stored in the `users.conf` file. Your file extension must be *.conf* in order to use this user service. - -The `users.conf` file uses a Git-style configuration format: - - [user "admin"] - password = admin - role = "#admin" - role = "#notfederated" - repository = RW+:repo1.git - repository = RW+:repo2.git - - [user "hannibal"] - password = bossman - repository = RWD:topsecret.git - repository = RW+:ateam/[A-Za-z0-9-~_\\./]+ - - [user "faceman"] - password = vanity - - [user "murdock"] - password = crazy - - [user "babaracus"] - password = grrrr - - [team "ateam"] - user = hannibal - user = faceman - user = murdock - user = babaracus - repository = RW:topsecret.git - mailingList = list@ateam.org - postReceiveScript = sendmail - -The `users.conf` file allows flexibility for adding new fields to a UserModel object without imposing the complexity of relying on an embedded SQL database. - -### Usernames -Usernames must be unique and are case-insensitive. -Whitespace is illegal. - -### Passwords -User passwords are CASE-SENSITIVE and may be *plain*, *md5*, or *combined-md5* formatted (see `gitblit.properties` -> *realm.passwordStorage*). - -### User Roles -There are four actual *roles* in Gitblit: - -- *#admin*, which grants administrative powers to that user for all repositories, users, and teams -- *#notfederated*, which prevents an account from being pulled by another Gitblit instance -- *#create*, which allows the user the power to create personal repositories -- *#fork*, which allows the user to create a personal fork of an existing Gitblit-hosted repository - -**NOTE:** -The following repository permissions are equivalent: - -- myrepo.git -- RW+:myrepo.git - -This is to preserve backwards-compatibility with Gitblit <= 1.1.0 which granted rewind power to all access-permitted users. - -### Personal Repositories & Forks - -Personal Repositories and Forks are related but are controlled individually. - -#### Creating a Personal Repository -A user may be granted the power to create personal repositories by specifying the *#create* role through the web ui or through the RPC mechanism via the Gitblit Manager. Personal repositories are exactly like common/shared repositories except that the owner has a few additional administrative powers for that repository, like rename and delete. - -#### Creating a Fork -A user may also be granted the power to fork an existing repository hosted on your Gitblit server to their own personal clone by specifying the *#fork* role through the web ui or via the Gitblit Manager. - -Forks are mostly likely personal repositories or common/shared repositories except for two important differences: - -1. Forks inherit a view/clone access list from the origin repository. -i.e. if Team A has clone access to the origin repository, then by default Team A also has clone access to the fork. This is to facilitate collaboration. -2. Forks are always listed in the fork network, regardless of any access restriction set on the fork. -In other words, if you fork *RepoA.git* to *~me/RepoA.git* and then set the access restriction of *~me/RepoA.git* to *Authenticated View, Clone, & Push* your fork will still be listed in the fork network for *RepoA.git*. - -If you really must have an invisible fork, the clone it locally, create a new personal repository for your invisible fork, and push it back to that personal repository. - diff --git a/src/site/setup_authentication.mkd b/src/site/setup_authentication.mkd index d6956b18..7f606180 100644 --- a/src/site/setup_authentication.mkd +++ b/src/site/setup_authentication.mkd @@ -8,6 +8,7 @@ Gitblit supports additional authentication mechanisms aside from it's internal o * Windows authentication * Redmine auhentication * Salesforce.com authentication +* Servlet container authentication ### LDAP Authentication *SINCE 1.0.0* @@ -77,14 +78,36 @@ You can start Gitblit GO with an in-memory LDAP server by specifying the *--ldap ### Windows Authentication +Windows authentication is based on the use of Waffle and JNA. It is known to work properly for authenticating against the local Windows machine, but it is unclear if it works properly with a domain controller and Active Directory. To use this service, your Gitblit server must be installed on a Windows machine. + + realm.userService = com.gitblit.WindowsUserService + realm.windows.defaultDomain = + ### Redmine Authentication +You may authenticate your users against a Redmine installation as long as your Redmine install has properly enabled [API authentication](http://www.redmine.org/projects/redmine/wiki/Rest_Api#Authentication). This user service only supports user authentication; it does not support team creation based on Redmine groups. Redmine administrators will also be Gitblit administrators. + + realm.userService = com.gitblit.RedmineUserService + realm.redmine.url = http://example.com/redmine + ### Salesforce.com Authentication +You may authenticate your users against Salesforce.com. You can require that user's belong to a particular organization by specifying a non-zero organization id. + + realm.userService = com.gitblit.SalesforceUserService + realm.salesforce.orgId = 0 + +### Container Authentication + +If you are using the WAR variant and deploying into your own servlet container which has a pre-defined authentication mechanism protecting the Gitblit webapp, then you may instruct Gitblit to automatically create Gitblit accounts for container-authenticated user principals. + + realm.container.autoCreateAccounts = true + ## Custom Authentication + 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. -Please subclass [com.gitblit.GitblitUserService](https://github.com/gitblit/gitblit/blob/master/src/com/gitblit/GitblitUserService.java) and override the *setup()* and *authenticate()* methods. +Please subclass [com.gitblit.GitblitUserService](https://github.com/gitblit/gitblit/blob/master/src/main/java/com/gitblit/GitblitUserService.java) and override the *setup()* and *authenticate()* methods. Make sure to set the *serviceImpl* field in your *setup()* method. You may use your subclass by specifying its fully qualified classname in the *realm.userService* setting. @@ -92,10 +115,11 @@ You may use your subclass by specifying its fully qualified classname in the *re Your subclass must be on Gitblit's classpath and must have a public default constructor. ### Custom Everything -Instead of maintaining a `users.conf` or `users.properties` file, you may want to integrate Gitblit into an existing environment. + +Instead of maintaining a `users.conf` 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. Your user service class must be on Gitblit's classpath and must have a public default constructor. -Please see the following interface definition [com.gitblit.IUserService](https://github.com/gitblit/gitblit/blob/master/src/com/gitblit/IUserService.java). +Please see the following interface definition [com.gitblit.IUserService](https://github.com/gitblit/gitblit/blob/master/src/main/java/com/gitblit/IUserService.java). diff --git a/src/site/setup_proxy.mkd b/src/site/setup_proxy.mkd index 6e600f61..b169cefa 100644 --- a/src/site/setup_proxy.mkd +++ b/src/site/setup_proxy.mkd @@ -65,3 +65,27 @@ ProxyPreserveHost On 4. Set *web.mountParameters=false* in `gitblit.properties` or `web.xml` this will use parameterized URLs. Alternatively, you can respecify *web.forwardSlashCharacter*. +### Controlling Advertised Repository URLs + +In some reverse-proxy configurations you may be running Gitblit using an http interface with an https reverse-proxy proxy. This will lead to Gitblit generating incorrect repository urls. + +You can control the url that Gitblit generates by setting X-Forwarded headers in your proxy server. + +*X-Forwarded-Proto*://servername(:*X-Forwarded-Port*)(/*X-Forwarded-Context*) + +---X:MEDIAWIKI--- +{| class="table table-bordered" +! Header +! Description +|- +| X-Forwarded-Port +| The port to use in generated repository http/https urls +|- +| X-Forwarded-Proto +| The protocol/scheme to use in generated repository http/https urls +|- +| X-Forwarded-Context +| The context to use in generated repository http/https urls +|} +---X:MEDIAWIKI--- + diff --git a/src/site/setup_viewer.mkd b/src/site/setup_viewer.mkd new file mode 100644 index 00000000..03aa3490 --- /dev/null +++ b/src/site/setup_viewer.mkd @@ -0,0 +1,47 @@ +## Gitblit as a Viewer + +Gitblit is designed to be a complete Git server solution, however you may already have a Git serving solution such as ssh+gitolite or Gerrit. For these scenarios, you may configure Gitblit to be just a repository viewer. + +### Lock-down your Viewer + +Here is an example configuration that disables all administration, all Git serving features, and requires an authenticated user to view anything. + + git.repositoriesFolder = ${baseFolder}/git + git.cacheRepositoryList = true + git.searchRepositoriesSubfolders = true + git.searchRecursionDepth = -1 + git.searchExclusions = + git.daemonPort = 0 + git.enableGitServlet = false + git.enableGarbageCollection = false + git.defaultAccessRestriction = VIEW + web.authenticateViewPages = true + web.allowAdministration = false + web.enableRpcServlet = false + web.enableRpcManagement = false + web.enableRpcAdministration = false + web.allowForking = false + +### Tomcat or Reverse-Proxy Servers + +If you are running Gitblit on a Tomcat-based container you will likely run into forward-slash character troubles. + +To resolve this either set: + + web.mountParameters = false + +or + + web.forwardSlashCharacter = ! + + +### Advertised Repository Urls + +You may also want to advertise repository urls for your other Git serving solution from Gitblit. + +- *{0}* is the token for the repository name +- *{1}* is the token for the username + +The username is only practical if you have setup the account names for your other git serving solution to match the Gitblit account. + + web.otherUrls = ssh://localhost/git/{0} git://localhost:29418/git/{0} https://{1}@localhost/r/{0} -- cgit v1.2.3