Error: failed to parse markup
## 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.
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.
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
or whatever the url should be.
7. Enter the default administrator credentials: **admin / admin** and click the *Login* button
**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%).
*Its best to eliminate spaces in the path name.*
2. The server itself is configured through a simple text file.
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.
6. Enter the default administrator credentials: **admin / admin** and click the *Login* button
**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.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.
This will generate a new certificate and keystore for *your hostname* protected by *server.storePassword*.
**NOTE:**
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.
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.
Additional service definition options and runtime capabilities of `gitblitw.exe` (prunmgr.exe) are documented [here](http://commons.apache.org/daemon/procrun.html).
**NOTE:**
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.
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
Java Virtual Machine:
C:\Program Files\Java\jre6\bin\server\jvm.dll
#### 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
## 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
### 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 unique and 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.
### Administering Users
All users are stored in the `users.properties` file or in the file you specified in `gitblit.properties`.
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.
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 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.
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.
%BEGINCODE%
public interface IUserService {
/**
* Setup the user service.
*
* @param settings
* @since 0.7.0
*/
@Override
public void setup(IStoredSettings settings) {
}
/**
* 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.
**NOTE:**
The default self-signed certificate generated by Gitlbit GO is bound to *localhost*.
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.
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. Key = http.sslVerify
Value = false
- **Command-line Git** ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
git config --global --bool --add http.sslVerify false
### Cloning an Access Restricted Repository
- **Eclipse/EGit/JGit**
Nothing special to configure, EGit figures out everything.
https://yourserver/git/your/repository
- **Command-line Git**
My testing indicates that your username must be embedded in the url. YMMV.
https://username@yourserver/git/your/repository
