diff options
Diffstat (limited to 'docs/01_setup.mkd')
| -rw-r--r-- | docs/01_setup.mkd | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd new file mode 100644 index 00000000..8ad7c5ed --- /dev/null +++ b/docs/01_setup.mkd @@ -0,0 +1,129 @@ +## 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.
+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)
+ - <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 <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!!
+
+## Gitblit GO Setup
+
+1. Download and unzip [Gitblit GO %VERSION%](http://code.google.com/p/gitblit/downloads/detail?name=%GO%).<br/>
+*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)
+ - *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!
+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.
+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!!
+
+### Creating your own Self-Signed Certificate
+Gitblit GO automatically generates an ssl certificate for you that contains generic, non-personalized information.
+
+Should you want to include more personal or server-specific information in your self-signed certificate you will have to generate a new one.
+
+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!
+
+### 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.
+
+#### 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
+
+## 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
+
+#### 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/>
+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`.<br/>
+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.<br/>
+Whitespace is illegal.
+
+#### Passwords
+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.
+
+## 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.<br/>
+
+Your user service class must be on Gitblit's classpath and must have a public default constructor.
+
+## 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.
+
+- Eclipse/EGit
+ 1. Window->Preferences->Team->Git->Configuration
+ 2. Click the *New Entry* button
+ 3. <pre>Key = *http.sslVerify*
+ Value = *false*</pre>
+- Command-line Git ([Git-Config Manual Page](http://www.kernel.org/pub/software/scm/git/docs/git-config.html))
+ <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.
+ <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>
+
\ No newline at end of file |