| | |
|---|
| | | ## 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. Manual extraction depends on if your servlet container is configured to automatically deploy WAR files.
|
|---|
| | | 3. Copy the `WEB-INF/users.properties` file to a location outside the webapps folder but accessible by your servlet container. |
|---|
| | | 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)
|
|---|
| | |
|---|
| | | 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!! |
|---|
| | | **NOTE:** Make sure to change the administrator username and/or password!! |
|---|
| | |
|
|---|
| | | ## Gitblit GO Setup
|
|---|
| | |
|
|---|
| | |
|---|
| | | *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 my be relative or absolute)
|
|---|
| | | - *server.tempFolder* (path my be relative or absolute)
|
|---|
| | | - *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*<br/>
|
|---|
| | | **NOTE:** Consider using **https** exclusively because passwords for authentication are transmitted as clear text! |
|---|
| | | - *server.storePassword*<br/>
|
|---|
| | | **NOTE:** If you manually generate an ssl certificate, the certificate password AND the keystore password must match! |
|---|
| | | **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 certificate is generated.
|
|---|
| | | 5. Open your browser to <http://localhost> or <https://localhost> depending on your chosen configuration.
|
|---|
| | | 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:8080> or <https://localhost:8443> 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!! |
|---|
| | | **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 contains generic, non-personalized information.
|
|---|
| | | Gitblit GO automatically generates an ssl certificate for you that is bound to *localhost*.
|
|---|
| | |
|
|---|
| | | Should you want to include more personal or server-specific information in your self-signed certificate you will have to generate a new one.
|
|---|
| | | 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.
|
|---|
| | |
|
|---|
| | | 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*.
|
|---|
| | |
|
|---|
| | | Review the contents of the `makekeystore.cmd` or `makekeystore_jdk.cmd` script and execute it.<br/>
|
|---|
| | | **NOTE:** If you manually generate an ssl certificate, the certificate password AND the keystore password must match!
|
|---|
| | | **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
|
|---|
| | | Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your installed Java Virtual Machine.<br/>
|
|---|
| | | Set the *JVM* variable in the script to the location of your Java Virtual Machine, add any necessary start parameters, and execute the script.
|
|---|
| | | 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.
|
|---|
| | |
|---|
| | | **Example**
|
|---|
| | |
|
|---|
| | | java -jar gitblit.jar --userService c:\myrealm.properties --storePassword something
|
|---|
| | |
|
|---|
| | | ## Upgrading Gitblit
|
|---|
| | | Generally, upgrading is easy.
|
|---|
| | |
|
|---|
| | | 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.
|
|---|
| | |
|
|---|
| | | Any important changes to the setting keys or default values will always be mentioned in the [release log](releases.html).
|
|---|
| | |
|
|---|
| | | ### Upgrading Gitblit WAR
|
|---|
| | | 1. Backup your `web.xml` file
|
|---|
| | | 2. Delete currently deployed gitblit WAR
|
|---|
| | | 3. Deploy new WAR and overwrite the `web.xml` file with your backup
|
|---|
| | | 4. Review and optionally apply any new settings as indicated in the [release log](releases.html). |
|---|
| | | |
|---|
| | | ### Upgrading Gitblit GO
|
|---|
| | | |
|---|
| | | 1. Backup your `gitblit.properties` file
|
|---|
| | | 2. Backup your `users.properties` file *(if it is located in the Gitblit GO folder)*
|
|---|
| | | 3. Unzip Gitblit GO to a new folder
|
|---|
| | | 4. Overwrite the `gitblit.properties` file with your backup
|
|---|
| | | 5. Overwrite the `users.properties` file with your backup *(if it was located in the Gitblit GO folder)*
|
|---|
| | | 6. Review and optionally apply any new settings as indicated in the [release log](releases.html).
|
|---|
| | |
|
|---|
| | | #### Upgrading Windows Service
|
|---|
| | | You may need to delete your old service definition and install a new one depending on what has changed in the release. |
|---|
| | |
|
|---|
| | | ## Gitblit Configuration
|
|---|
| | |
|
|---|
| | |
|---|
| | | accessRestriction = clone
|
|---|
| | | isFrozen = false
|
|---|
| | | showReadme = false
|
|---|
| | | federationStrategy = FEDERATE_THIS
|
|---|
| | | isFederated = false
|
|---|
| | | federationSets = |
|---|
| | |
|
|---|
| | | #### 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/>
|
|---|
| | |
|---|
| | | 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.
|
|---|
| | | 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.
|
|---|
| | |
|
|---|
| | | ## Authentication and Authorization Customization
|
|---|
| | | Instead of maintaining a `users.properties` file, you may want to integrate Gitblit into an existing environment.
|
|---|
| | |
|---|
| | |
|
|---|
| | | 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<String> 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<String> 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<String> 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 not to verify the self-signed certificate in order to perform any remote Git operations.
|
|---|
| | | You must tell Git/JGit not to verify the self-signed certificate in order to perform any remote Git operations.
|
|---|
| | |
|
|---|
| | | - Eclipse/EGit
|
|---|
| | | **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.1.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*
|
|---|
| | |
|---|
| | | <pre>git config --global --bool --add http.sslVerify false</pre>
|
|---|
| | |
|
|---|
| | | ### Cloning an Access Restricted Repository
|
|---|
| | | - Eclipse/Egit<br/>Nothing special to configure, EGit figures out everything.
|
|---|
| | | - 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>
|
|---|
