Changes for minor 0.5.1 release.

* Clarified SSL certificate generation and configuration in light of the
hostname verificiation that JGit currently does despite
the http.sslVerify=false setting.

* Added some troubleshooting information related to filesystem
permissions and reading repositories.

* Switched from JavaService to Apache Commons Daemon.  Not sure what
happened to JavaService as it stopped working for me on Windows 7 with
Java 1.6.0_26.  Commons Daemon accomplishes the same thing and offers a
nice service control utility.

NOTICE

@@ -16,12 +16,12 @@ google-code-prettify
    http://code.google.com/p/google-code-prettify
 
 ---------------------------------------------------------------------------
-JavaService
+Commons Daemon
 ---------------------------------------------------------------------------
-   JavaService, released under the
-   BSD License and the Lesser GNU Public License.
+   Commons Daemon, released under the
+   Apache Software License, Version 2.0.
 
-   http://forge.ow2.org/projects/javaservice
+   http://commons.apache.org/daemon
 
 ---------------------------------------------------------------------------
 JGit

build.xml

@@ -23,10 +23,6 @@
 		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 	-->
 	<target name="buildinfo">
-		<!-- build date -->
-		<tstamp>
-			<format property="gb.buildDate" pattern="yyyy-MM-dd" />
-		</tstamp>
 
 		<!-- extract Gitblit version number from source code -->
 		<loadfile property="gb.version" srcfile="${basedir}/src/com/gitblit/Constants.java">
@@ -42,7 +38,22 @@
 				</tokenfilter>
 			</filterchain>
 		</loadfile>
-
+
+		<!-- extract Gitblit version date from source code -->
+		<loadfile property="gb.versionDate" srcfile="${basedir}/src/com/gitblit/Constants.java">
+			<filterchain>
+				<linecontains>
+					<contains value="public static final String VERSION_DATE = " />
+				</linecontains>
+				<striplinebreaks />
+				<tokenfilter>
+					<replacestring from="public static final String VERSION_DATE = &quot;" to="" />
+					<replacestring from="&quot;;" to="" />
+					<trim />
+				</tokenfilter>
+			</filterchain>
+		</loadfile>
+
 		<!-- extract JGit version number from source code -->
 		<loadfile property="jgit.version" srcfile="${basedir}/src/com/gitblit/Constants.java">
 			<filterchain>
@@ -229,7 +240,7 @@
 				<arg value="%WAR%=${distribution.warfile}" />
 
 				<arg value="--substitute" />
-				<arg value="%BUILDDATE%=${gb.buildDate}" />
+				<arg value="%BUILDDATE%=${gb.versionDate}" />
 
 				<arg value="--substitute" />
 				<arg value="%JGIT%=${jgit.version}" />
@@ -424,7 +435,7 @@
 			<arg value="%WAR%=${distribution.warfile}" />
 
 			<arg value="--substitute" />
-			<arg value="%BUILDDATE%=${gb.buildDate}" />
+			<arg value="%BUILDDATE%=${gb.versionDate}" />
 
 			<arg value="--substitute" />
 			<arg value="%JGIT%=${jgit.version}" />

distrib/gitblit.properties

@@ -61,7 +61,7 @@ web.siteName =
 # functions.  
 web.allowAdministration = true
 
-# Allow dyanamic zip downloads.   
+# Allow dynamic zip downloads.   
 web.allowZipDownloads = true
 
 # Default number of entries to include in RSS Syndication links

distrib/installService.cmd

@@ -1,2 +1,38 @@
-set JVM=C:\Program Files\Java\jdk1.6.0_26
-JavaService.exe -install gitblit "%JVM%\jre\bin\server\jvm.dll" -Xmx1024M -Djava.class.path=%CD%\gitblit.jar;"%JVM%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword gitblit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD%
+@REM Install Gitblit as a Windows service.
+
+@REM gitblitw.exe (prunmgr.exe) is a GUI application for monitoring 
+@REM and configuring the Gitblit procrun service.
+@REM
+@REM By default this tool launches the service properties dialog
+@REM but it also has some other very useful functionality.
+@REM
+@REM http://commons.apache.org/daemon/procrun.html
+
+@REM arch = x86, amd64, or ia32
+SET ARCH=amd64
+
+@REM Be careful not to introduce trailing whitespace after the ^ characters.
+@REM Use ; or # to separate values in the --StartParams parameter.
+"%CD%\%ARCH%\prunsrv.exe"  //IS//gitblit ^
+		 --DisplayName="gitblit" ^
+		 --Description="a pure Java Git solution" ^
+		 --Startup=auto ^
+		 --LogPath="%CD%\logs" ^
+		 --LogLevel=INFO ^
+		 --LogPrefix=gitblit ^
+		 --StdOutput=auto ^
+		 --StdError=auto ^
+		 --StartPath="%CD%" ^
+		 --StartClass=com.gitblit.Launcher ^
+		 --StartMethod=main ^
+		 --StartParams="--storePassword;gitblit" ^
+		 --StartMode=jvm ^
+		 --StopPath="%CD%" ^
+		 --StopClass=com.gitblit.Launcher ^
+		 --StopMethod=main ^
+		 --StopParams="--stop" ^
+		 --StopMode=jvm ^
+		 --Classpath="%CD%\gitblit.jar" ^
+		 --Jvm=auto ^
+		 --JvmMx=1024
+

distrib/makekeystore.cmd

@@ -1,2 +1,6 @@
+@REM --------------------------------------------------------------------------
+@REM Set HOSTNAME to the server's hostname
+@REM --------------------------------------------------------------------------
+@SET HOSTNAME=localhost
 @del keystore
-@java -cp gitblit.jar;"%CD%\ext\*" com.gitblit.MakeCertificate --alias localhost  --subject "CN=localhost, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US"
+@java -cp gitblit.jar;"%CD%\ext\*" com.gitblit.MakeCertificate --hostname %HOSTNAME% --subject "CN=%HOSTNAME%, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US"

distrib/makekeystore_jdk.cmd

@@ -1,2 +1,6 @@
+@REM --------------------------------------------------------------------------
+@REM Set HOSTNAME to the server's hostname
+@REM --------------------------------------------------------------------------
+@SET HOSTNAME=localhost
 @del keystore
-@keytool -keystore keystore -alias localhost -genkey -keyalg RSA -dname "CN=localhost, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US"
+@keytool -keystore keystore -alias %HOSTNAME% -genkey -keyalg RSA -dname "CN=%HOSTNAME%, OU=Gitblit, O=Gitblit, L=Some Town, ST=Some State, C=US"

distrib/uninstallService.cmd

@@ -1 +1,5 @@
-javaservice -uninstall gitblit
+@REM arch = x86, amd64, or ia32
+SET ARCH=amd64
+
+@REM Delete the gitblit service
+"%CD%\%ARCH%\prunsrv.exe" //DS//gitblit

docs/01_features.mkd

@@ -33,14 +33,16 @@
 
 ## Gitblit GO Features
 - Out-of-the-box integrated stack requiring minimal configuration
-- Automatically generates a self-signed certificate for https communications
+- Automatically generates a self-signed certificate for *localhost* https communications<br/>(includes script to generate a self-signed certificate for *your hostname*, see [setup](/setup.html) for details)
 - Single text file for configuring server and gitblit
+- A Windows service installation script and configuration tool
 
 ## Limitations
 - HTTP/HTTPS are the only supported protocols
 - Access controls are not path-based, they are repository-based
 - Only Administrators can create, rename or delete repositories
 - Only Administrators can create, modify or delete users
+- Native Git may be needed to periodically run git-gc as [JGit][jgit] does not fully support the git-gc featureset.
 
 ### Caveats
 - Gitblit may eat your data.  Use at your own risk.
@@ -49,7 +51,6 @@
 ## Todo List
 - Code documentation
 - Unit testing
-- Update to JGit 1.0.0 when JGit team provides Maven artifacts
 
 ### Under Consideration
 - Clone remote repository feature
@@ -61,4 +62,6 @@
     - activity/timeline
     - query feature with paging support
     - change history
-- Ticgit write integration
+- Ticgit write integration
+
+[jgit]: http://eclipse.org/jgit "Eclipse JGit Site"

docs/01_setup.mkd

@@ -1,46 +1,66 @@
 ## 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:
     - &lt;context-parameter&gt; *git.repositoryFolder* (set the full path to your repositories folder)
     - &lt;context-parameter&gt; *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!! 
+    **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)
+    - *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 @@ Your user service class must be on Gitblit's classpath and must have a public de
 
 ## 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 @@ You must tell Git not to verify the self-signed certificate in order to perform
     <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>