From d39680e9f54322ddcb40b00503a8ee30aee6c99c Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Tue, 28 Jun 2011 20:12:51 -0400
Subject: [PATCH] Changes for minor 0.5.1 release.
---
docs/01_setup.mkd | 63 ++++++++++++++++++++++---------
1 files changed, 44 insertions(+), 19 deletions(-)
diff --git a/docs/01_setup.mkd b/docs/01_setup.mkd
index 8ad7c5e..eca0be2 100644
--- a/docs/01_setup.mkd
+++ b/docs/01_setup.mkd
@@ -1,8 +1,8 @@
## 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)
@@ -10,7 +10,7 @@
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
@@ -18,29 +18,49 @@
*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.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.
+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> 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!!
+ **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.0.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.
#### Command-Line Parameters
Command-Line parameters override the values in `gitblit.properties` at runtime.
@@ -111,9 +131,14 @@
## 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.0.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*
@@ -122,7 +147,7 @@
<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>
--
Gitblit v1.9.1