From 230632f582e7f1647cf15bc3ebd6148cb9af43c0 Mon Sep 17 00:00:00 2001 From: James Moger Date: Wed, 20 Jul 2011 16:08:18 -0400 Subject: Documentation and build script improvements. --- docs/00_index.mkd | 12 +++-- docs/01_setup.mkd | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++- docs/02_faq.mkd | 5 +- docs/04_releases.mkd | 12 +++-- 4 files changed, 156 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/00_index.mkd b/docs/00_index.mkd index a2f83132..62631bcd 100644 --- a/docs/00_index.mkd +++ b/docs/00_index.mkd @@ -23,9 +23,15 @@ Gitblit requires a Java 6 Runtime Environment (JRE) or a Java 6 Development Kit **%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%)|[war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%)) based on [%JGIT%][jgit]   *released %BUILDDATE%* -- forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers
**New:** *web.forwardSlashCharacter = /* -- optionally display repository on-disk size on repositories page
**New:** *web.showRepositorySizes = true* -- tone-down repository group header color +- fixed: bare-cloned repositories were listed as (empty) and were not clickable (issue 13) +- fixed: default port for Gitblit GO is now 8443 to be more linux/os x friendly (issue 12) +- fixed: forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers
**New:** *web.forwardSlashCharacter = /* (issue 11) +- fixed: users can now change their passwords (issue 1) +- fixed: always show root repository group first, i.e. don't sort root group with other groups +- fixed: tone-down repository group header color +- added: optionally display repository on-disk size on repositories page
**New:** *web.showRepositorySizes = true* +- updated: MarkdownPapers 1.1.0 +- updated: Jetty 7.4.4 issues & binaries @ [Google Code][googlecode]
sources @ [Github][gitbltsrc] diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd index d595a992..48955dba 100644 --- a/docs/01_setup.mkd +++ b/docs/01_setup.mkd @@ -20,11 +20,12 @@ Open `web.xml` in your favorite text editor and make sure to review and set: 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.httpPort* and *server.httpsPort*
- *server.httpBindInterface* and *server.httpsBindInterface*
**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.
Please see the section titled **Creating your own Self-Signed Certificate** to generate a certificate for *your hostname*. -5. Open your browser to or depending on your chosen configuration. +5. Open your browser to or depending on your chosen configuration. 6. Click the *Login* link and enter the default administrator credentials: **admin / admin**
**NOTE:** Make sure to change the administrator username and/or password!! @@ -164,6 +165,138 @@ You may use your own custom *com.gitblit.IUserService* implementation by specify Your user service class must be on Gitblit's classpath and must have a public default constructor. +%BEGINCODE% +public interface IUserService { + + /** + * Does the user service support cookie authentication? + * + * @return true or false + */ + boolean supportsCookies(); + + /** + * Returns the cookie value for the specified user. + * + * @param model + * @return cookie value + */ + char[] getCookie(UserModel model); + + /** + * Authenticate a user based on their cookie. + * + * @param cookie + * @return a user object or null + */ + UserModel authenticate(char[] cookie); + + /** + * Authenticate a user based on a username and password. + * + * @param username + * @param password + * @return a user object or null + */ + UserModel authenticate(String username, char[] password); + + /** + * Retrieve the user object for the specified username. + * + * @param username + * @return a user object or null + */ + UserModel getUserModel(String username); + + /** + * Updates/writes a complete user object. + * + * @param model + * @return true if update is successful + */ + boolean updateUserModel(UserModel model); + + /** + * Adds/updates a user object keyed by username. This method allows for + * renaming a user. + * + * @param username + * the old username + * @param model + * the user object to use for username + * @return true if update is successful + */ + boolean updateUserModel(String username, UserModel model); + + /** + * Deletes the user object from the user service. + * + * @param model + * @return true if successful + */ + boolean deleteUserModel(UserModel model); + + /** + * Delete the user object with the specified username + * + * @param username + * @return true if successful + */ + boolean deleteUser(String username); + + /** + * Returns the list of all users available to the login service. + * + * @return list of all usernames + */ + List getAllUsernames(); + + /** + * Returns the list of all users who are allowed to bypass the access + * restriction placed on the specified repository. + * + * @param role + * the repository name + * @return list of all usernames that can bypass the access restriction + */ + List getUsernamesForRepositoryRole(String role); + + /** + * Sets the list of all uses who are allowed to bypass the access + * restriction placed on the specified repository. + * + * @param role + * the repository name + * @param usernames + * @return true if successful + */ + boolean setUsernamesForRepositoryRole(String role, List usernames); + + /** + * Renames a repository role. + * + * @param oldRole + * @param newRole + * @return true if successful + */ + boolean renameRepositoryRole(String oldRole, String newRole); + + /** + * Removes a repository role from all users. + * + * @param role + * @return true if successful + */ + boolean deleteRepositoryRole(String role); + + /** + * @See java.lang.Object.toString(); + * @return string representation of the login service + */ + String toString(); +} +%ENDCODE% + ## 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. diff --git a/docs/02_faq.mkd b/docs/02_faq.mkd index a1fcf139..8d8bb6a2 100644 --- a/docs/02_faq.mkd +++ b/docs/02_faq.mkd @@ -37,7 +37,10 @@ Run the server as *root* (security concern) or change the ports you are serving Confirm that the <context-param> *realm.userService* value in your `web.xml` file actually points to a `users.properties` file. ### Gitblit won't open my grouped repository (/group/myrepo.git) or browse my branch/tag/ref?! -This is likely an url encoding/decoding problem. In `gitblit.properties` or `web.xml`, try setting *web.mountParameters* to *false*. +This is likely an url encoding/decoding problem related to your servlet container's security. There are two possible workarounds for this issue. In `gitblit.properties` or `web.xml`: + +1. try setting *web.mountParameters* to *false*.
This changes the url scheme from mounted (*/commit/myrepo.git/abcdef*) to parameterized (*/commit/?r=myrepo.git&h=abcdef*). +2. try changing *web.forwardSlashCharacter* to an asterisk or a **!** ## General Interest Questions diff --git a/docs/04_releases.mkd b/docs/04_releases.mkd index 559b1327..13f3dccb 100644 --- a/docs/04_releases.mkd +++ b/docs/04_releases.mkd @@ -3,9 +3,15 @@ ### Current Release **%VERSION%** ([go](http://code.google.com/p/gitblit/downloads/detail?name=%GO%)|[war](http://code.google.com/p/gitblit/downloads/detail?name=%WAR%)) based on [%JGIT%][jgit]   *released %BUILDDATE%* -- forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers
**New:** *web.forwardSlashCharacter = /* -- optionally display repository on-disk size on repositories page
**New:** *web.showRepositorySizes = true* -- tone-down repository group header color +- fixed: bare-cloned repositories were listed as (empty) and were not clickable (issue 13) +- fixed: default port for Gitblit GO is now 8443 to be more linux/os x friendly (issue 12) +- fixed: forward-slashes ('/', %2F) can be encoded using a custom character to workaround some servlet container default security measures for proxy servers
**New:** *web.forwardSlashCharacter = /* (issue 11) +- fixed: users can now change their passwords (issue 1) +- fixed: always show root repository group first, i.e. don't sort root group with other groups +- fixed: tone-down repository group header color +- added: optionally display repository on-disk size on repositories page
**New:** *web.showRepositorySizes = true* +- updated: MarkdownPapers 1.1.0 +- updated: Jetty 7.4.4 ### Older Releases **0.5.1** ([go](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.5.1.zip)|[war](http://code.google.com/p/gitblit/downloads/detail?name=gitblit-0.5.1.war)) based on [JGit 1.0.0 (201106090707-r)][jgit]   *released 2006-06-28* -- cgit v1.2.3