From dd7961bc443c732d0bbdd6bda47d6c2cfda5b290 Mon Sep 17 00:00:00 2001 From: James Moger Date: Tue, 17 May 2011 22:06:07 -0400 Subject: Building site content and documentation from Markdown. --- .gitignore | 1 + build.xml | 51 ++++++++-- distrib/UninstallService.bat | 1 - distrib/UninstallService64.bat | 1 - distrib/gitblit.properties | 6 +- distrib/installService.bat | 2 - distrib/installService.cmd | 2 + distrib/installService64.bat | 2 - distrib/installService64.cmd | 2 + distrib/makekeystore.cmd | 2 + distrib/uninstallService.cmd | 1 + distrib/uninstallService64.cmd | 1 + docs/00_overview.mkd | 87 ++++++++++++++++ docs/01_configuration.mkd | 73 ++++++++++++++ docs/01_eclipse.mkd | 5 + docs/01_faq.mkd | 1 + docs/01_releases.mkd | 1 + docs/01_screenshots.mkd | 3 + docs/architecture.odg | Bin 0 -> 13340 bytes docs/architecture.png | Bin 0 -> 16892 bytes docs/page_footer.html | 6 ++ docs/page_header.html | 17 ++++ src/com/gitblit/BuildSite.java | 136 ++++++++++++++++++++++++++ src/com/gitblit/Constants.java | 2 + src/com/gitblit/wicket/resources/markdown.css | 13 +++ 25 files changed, 399 insertions(+), 17 deletions(-) delete mode 100644 distrib/UninstallService.bat delete mode 100644 distrib/UninstallService64.bat delete mode 100644 distrib/installService.bat create mode 100644 distrib/installService.cmd delete mode 100644 distrib/installService64.bat create mode 100644 distrib/installService64.cmd create mode 100644 distrib/makekeystore.cmd create mode 100644 distrib/uninstallService.cmd create mode 100644 distrib/uninstallService64.cmd create mode 100644 docs/00_overview.mkd create mode 100644 docs/01_configuration.mkd create mode 100644 docs/01_eclipse.mkd create mode 100644 docs/01_faq.mkd create mode 100644 docs/01_releases.mkd create mode 100644 docs/01_screenshots.mkd create mode 100644 docs/architecture.odg create mode 100644 docs/architecture.png create mode 100644 docs/page_footer.html create mode 100644 docs/page_header.html create mode 100644 src/com/gitblit/BuildSite.java diff --git a/.gitignore b/.gitignore index 2aa1fab6..6ba70733 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ /*.zip /gitblit.properties /users.properties +/site \ No newline at end of file diff --git a/build.xml b/build.xml index 22f23360..a25ba329 100644 --- a/build.xml +++ b/build.xml @@ -3,27 +3,27 @@ - + - + - - - - - - + + + + + + Building Git:Blit ${gb.version} - + @@ -31,7 +31,7 @@ - + @@ -98,5 +98,36 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/distrib/UninstallService.bat b/distrib/UninstallService.bat deleted file mode 100644 index a483c55d..00000000 --- a/distrib/UninstallService.bat +++ /dev/null @@ -1 +0,0 @@ -javaservice -uninstall gitblit \ No newline at end of file diff --git a/distrib/UninstallService64.bat b/distrib/UninstallService64.bat deleted file mode 100644 index 91f0c840..00000000 --- a/distrib/UninstallService64.bat +++ /dev/null @@ -1 +0,0 @@ -javaservice64 -uninstall gitblit \ No newline at end of file diff --git a/distrib/gitblit.properties b/distrib/gitblit.properties index bcbd3db4..e13b60cf 100644 --- a/distrib/gitblit.properties +++ b/distrib/gitblit.properties @@ -146,11 +146,15 @@ server.httpPort = 0 server.httpsPort = 443 # Specify the interface for Jetty to bind the standard connector. -# You may specify an ip or an empty value to bind to all interfaces. +# You may specify an ip or an empty value to bind to all interfaces. +# Specifying localhost will result in Git:Blit ONLY listening to requests to +# localhost. server.httpBindInterface = localhost # Specify the interface for Jetty to bind the secure connector. # You may specify an ip or an empty value to bind to all interfaces. +# Specifying localhost will result in Git:Blit ONLY listening to requests to +# localhost. server.httpsBindInterface = localhost # Password for SSL keystore. diff --git a/distrib/installService.bat b/distrib/installService.bat deleted file mode 100644 index 5b0df2c6..00000000 --- a/distrib/installService.bat +++ /dev/null @@ -1,2 +0,0 @@ -set JDK=C:\Program Files\Java\jdk1.6.0_21 -JavaService.exe -install gitblit "%JDK%\jre\bin\server\jvm.dll" -Xmx1024M -Djava.class.path=%CD%\gitblit.jar;"%JDK%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword dosomegit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD% \ No newline at end of file diff --git a/distrib/installService.cmd b/distrib/installService.cmd new file mode 100644 index 00000000..5b0df2c6 --- /dev/null +++ b/distrib/installService.cmd @@ -0,0 +1,2 @@ +set JDK=C:\Program Files\Java\jdk1.6.0_21 +JavaService.exe -install gitblit "%JDK%\jre\bin\server\jvm.dll" -Xmx1024M -Djava.class.path=%CD%\gitblit.jar;"%JDK%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword dosomegit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD% \ No newline at end of file diff --git a/distrib/installService64.bat b/distrib/installService64.bat deleted file mode 100644 index 08761f86..00000000 --- a/distrib/installService64.bat +++ /dev/null @@ -1,2 +0,0 @@ -set JDK=C:\Program Files\Java\jdk1.6.0_21 -JavaService64.exe -install gitblit "%JDK%\jre\bin\server\jvm.dll" -Djava.class.path=%CD%\gitblit.jar;"%JDK%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword dosomegit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD% \ No newline at end of file diff --git a/distrib/installService64.cmd b/distrib/installService64.cmd new file mode 100644 index 00000000..08761f86 --- /dev/null +++ b/distrib/installService64.cmd @@ -0,0 +1,2 @@ +set JDK=C:\Program Files\Java\jdk1.6.0_21 +JavaService64.exe -install gitblit "%JDK%\jre\bin\server\jvm.dll" -Djava.class.path=%CD%\gitblit.jar;"%JDK%\lib\tools.jar" -start com.gitblit.Launcher -params --storePassword dosomegit -stop com.gitblit.Launcher -params --stop -out %CD%\logs\stdout.log -err %CD%\logs\stderr.log -current %CD% \ No newline at end of file diff --git a/distrib/makekeystore.cmd b/distrib/makekeystore.cmd new file mode 100644 index 00000000..34a11b21 --- /dev/null +++ b/distrib/makekeystore.cmd @@ -0,0 +1,2 @@ +@del keystore +@keytool -keystore keystore -alias localhost -genkey -keyalg RSA -dname "CN=localhost, OU=Git:Blit, O=Git:Blit, L=Some Town, ST=Some State, C=US" \ No newline at end of file diff --git a/distrib/uninstallService.cmd b/distrib/uninstallService.cmd new file mode 100644 index 00000000..a483c55d --- /dev/null +++ b/distrib/uninstallService.cmd @@ -0,0 +1 @@ +javaservice -uninstall gitblit \ No newline at end of file diff --git a/distrib/uninstallService64.cmd b/distrib/uninstallService64.cmd new file mode 100644 index 00000000..91f0c840 --- /dev/null +++ b/distrib/uninstallService64.cmd @@ -0,0 +1 @@ +javaservice64 -uninstall gitblit \ No newline at end of file diff --git a/docs/00_overview.mkd b/docs/00_overview.mkd new file mode 100644 index 00000000..63898f6c --- /dev/null +++ b/docs/00_overview.mkd @@ -0,0 +1,87 @@ +## Overview +Git:Blit is an open-source, integrated pure-Java stack for managing, viewing, and serving [Git](http://git-scm.com) repositories. +Its designed primarily as a tool for small workgroups who want to host Git repositories on a Windows machine. + +Of course, since its pure-Java it should run with any JVM on any platform, but there are already [many compelling Git solutions](https://git.wiki.kernel.org/index.php/InterfacesFrontendsAndTools) for non-Windows environments. + +### Current Version + +[{0}](http://gitblit.com/{1}) based on [{2}](http://eclipse.org/jgit)   (*{3}*) + +### Features +- Out-of-the-box integrated stack requiring minimal configuration +- JGit SmartHTTP Servlet +- Web and Git Servlet authentication +- Four repository access control configurations + - *Anonymous View, Clone & Push* + - *Authenticated Push* + - *Authenticated Clone & Push* + - *Authenticated View, Clone & Push* +- Gitweb inspired UI (mostly plain html) +- Repository administration through web UI +- User administration through web UI +- Automatically generates a self-signed certificate for https communications +- Dates can optionally be displayed using browser's reported timezone +- Author and Committer email address display can be controlled +- Syntax highlighting +- Customizable regular expression handling for commit messages +- Simple repository stats +- Simple text file for server configuration +- Simple text file for users configuration +- Optional integrated Ticgit +- Optional integrated Markdown + +### Limitations +- HTTP/HTTPS are the only supported protocols +- Access controls are not path-based, they are repository-based +- Only admin users can create repositories +- Git:Blit is a full-stack solution, its not just a webapp so at this time there is no WAR build + +### Todo List +- Review spots where Git:Blit can cache data instead of abusing the disk +- Ticgit activity/timeline +- Ticgit query feature with paging support +- Ticgit ticket change history +- Implement Markdown editing +- View images on Blob page +- View other binary files Blob page + +### License +TBD + +### Architecture + +![block diagram](architecture.png "Git Blit Architecture") + +### Bundled Dependencies +The following dependencies are bundled with the Git:Blit zip file. + +- [google-code-prettify](http://code.google.com/p/google-code-prettify) +- [JavaService](http://forge.ow2.org/projects/javaservice) +- icons courtesy of [FatCow Hosting](http://www.fatcow.com/free-icons) + +### Downloaded Dependencies +The following dependencies are automatically downloaded from the Apache Maven repository and from the Eclipse Maven repository when Git:Blit is launched for the first time. + +- [JGit](http://eclipse.org/jgit) +- [Wicket](http://wicket.apache.org) +- [WicketStuff GoogleCharts](https://github.com/wicketstuff/core/wiki/GoogleCharts) +- [MarkdownPapers](http://markdown.tautua.org) +- [Jetty](http://eclipse.org/jetty) +- [SLF4J](http://www.slf4j.org) +- [Log4j](http://logging.apache.org/log4j) +- [JCommander](http://jcommander.org) +- [BouncyCastle](http://www.bouncycastle.org) + +### Building +Eclipse is recommended for development as the project settings are preconfigured. + +1. Clone the git repository from here. +2. Import the gitblit project into your Eclipse workspace.
+*There will be lots of build errors.* +3. Using Ant, execute the `build.xml` script in the project root.
+*This will download all necessary build dependencies and will also generate the Keys class for accessing settings.* +4. Select your gitblit project root and **Refresh** the project, this should correct all build problems. +5. Review the settings in `gitblit.properties` in your project root.
+Make sure you set an appropriate value for *git.repositoriesFolder*. +6. Execute the *com.gitblit.Launcher* class to start Git:Blit. \ No newline at end of file diff --git a/docs/01_configuration.mkd b/docs/01_configuration.mkd new file mode 100644 index 00000000..9e8a9f06 --- /dev/null +++ b/docs/01_configuration.mkd @@ -0,0 +1,73 @@ +## Setup and Configuration + +1. Download and unzip Git:Blit.
+*Its best to eliminate spaces in the path name as that can cause troubleshooting headaches.* +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* + - *server.tempFolder* + - *server.httpBindInterface* and *server.httpsBindInterface* + - *server.storePassword*
+**NOTE:**
+Its recommended to use **https** wherever possible instead of http because passwords are transmitted as clear text! +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 or depending on your chosen configuration. +6. Click the *Login* link and enter the default administrator credentials: **admin / admin**
+**NOTE:**
+Make sure to change the administrator username and/or password!! + +### Administering Repositories +Repositories can be created, edited, and deleted through the web UI. They may also be created, edited, and deleted from the command-line using real Git 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 = Joe Owner + useTickets = false + useDocs = true + showRemoteBranches = false + accessRestriction = clone + +#### Repository Names +Repository names must be unique and are case-insensitive. The name must be composed of letters, digits, or `/ _ - .`
+Whitespace is illegal. + +### Administering Users +In contrast, all users are stored in the `users.properties` file or in the file your 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 *crypt* formatted (see `gitblit.properties` -> *realm.passwordStorage*). + +#### User Roles +There is only one actual *role* in Git:Blit and that is *#admin* which grants administrative powers to that user. Administrators automatically have access to all repositories. All other *roles* are actually 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. + +### Creating your own Self-Signed Certificate + +Review the contents of the `makekeystore.cmd` or `makekeystore_jdk.cmd`script and execute it. Voila. + +### Running as a Service +Review the contents of the `installService.cmd` or `installService64.cmd`, as appropriate for your JVM.
+Set the *JDK* variable in the script to the location of your JDK, add any necessary start parameters, and execute the script. + +#### Command-Line Parameters + --tempFolder Server temp folder + --repositoriesFolder Git Repositories Folder + --realmFile Users Realm Hash File + --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) + +**Example** + + java -jar gitblit.jar --realmFile c:\myrealm.txt --storePassword something \ No newline at end of file diff --git a/docs/01_eclipse.mkd b/docs/01_eclipse.mkd new file mode 100644 index 00000000..93fd5315 --- /dev/null +++ b/docs/01_eclipse.mkd @@ -0,0 +1,5 @@ +## Eclipse Tips + +verifySsl + +how to push new unshared project to new repository \ No newline at end of file diff --git a/docs/01_faq.mkd b/docs/01_faq.mkd new file mode 100644 index 00000000..c92bfabd --- /dev/null +++ b/docs/01_faq.mkd @@ -0,0 +1 @@ +## Frequently Asked Questions diff --git a/docs/01_releases.mkd b/docs/01_releases.mkd new file mode 100644 index 00000000..7c0c2040 --- /dev/null +++ b/docs/01_releases.mkd @@ -0,0 +1 @@ +## Release History diff --git a/docs/01_screenshots.mkd b/docs/01_screenshots.mkd new file mode 100644 index 00000000..666e943f --- /dev/null +++ b/docs/01_screenshots.mkd @@ -0,0 +1,3 @@ +## Screenshots + +![test](gitblt_25.png "Optional Title") \ No newline at end of file diff --git a/docs/architecture.odg b/docs/architecture.odg new file mode 100644 index 00000000..fc4ea7b7 Binary files /dev/null and b/docs/architecture.odg differ diff --git a/docs/architecture.png b/docs/architecture.png new file mode 100644 index 00000000..d2f3e0c7 Binary files /dev/null and b/docs/architecture.png differ diff --git a/docs/page_footer.html b/docs/page_footer.html new file mode 100644 index 00000000..80b14d0c --- /dev/null +++ b/docs/page_footer.html @@ -0,0 +1,6 @@ + + + + \ No newline at end of file diff --git a/docs/page_header.html b/docs/page_header.html new file mode 100644 index 00000000..d282f54d --- /dev/null +++ b/docs/page_header.html @@ -0,0 +1,17 @@ + + + Git:Blit + + + + + + + + +
\ No newline at end of file diff --git a/src/com/gitblit/BuildSite.java b/src/com/gitblit/BuildSite.java new file mode 100644 index 00000000..ae85c062 --- /dev/null +++ b/src/com/gitblit/BuildSite.java @@ -0,0 +1,136 @@ +package com.gitblit; + +import java.io.BufferedReader; +import java.io.File; +import java.io.FileInputStream; +import java.io.FileOutputStream; +import java.io.FilenameFilter; +import java.io.InputStreamReader; +import java.io.OutputStreamWriter; +import java.nio.charset.Charset; +import java.text.MessageFormat; +import java.text.SimpleDateFormat; +import java.util.Arrays; +import java.util.Date; + +import com.beust.jcommander.JCommander; +import com.beust.jcommander.Parameter; +import com.beust.jcommander.ParameterException; +import com.beust.jcommander.Parameters; +import com.gitblit.utils.MarkdownUtils; + +public class BuildSite { + + public static void main(String... args) { + Params params = new Params(); + JCommander jc = new JCommander(params); + try { + jc.parse(args); + } catch (ParameterException t) { + usage(jc, t); + } + + File sourceFolder = new File(params.sourceFolder); + File destinationFolder = new File(params.outputFolder); + File[] markdownFiles = sourceFolder.listFiles(new FilenameFilter() { + + @Override + public boolean accept(File dir, String name) { + return name.toLowerCase().endsWith(".mkd"); + } + }); + Arrays.sort(markdownFiles); + + System.out.println(MessageFormat.format("Generating site from {0} Markdown Docs in {1} ", markdownFiles.length, sourceFolder.getAbsolutePath())); + String linkPattern = "{1}"; + StringBuilder sb = new StringBuilder(); + for (File file : markdownFiles) { + String displayName = getDocumentName(file); + String fileName = displayName + ".html"; + sb.append(MessageFormat.format(linkPattern, fileName, displayName)); + sb.append(" | "); + } + sb.setLength(sb.length() - 3); + sb.trimToSize(); + String html_header = readContent(new File(params.pageHeader)); + String html_footer = readContent(new File(params.pageFooter)); + final String links = sb.toString(); + final String header = MessageFormat.format(html_header, Constants.FULL_NAME, links); + final String date = new SimpleDateFormat("yyyy MMM dd").format(new Date()); + final String footer = MessageFormat.format(html_footer, "generated " + date); + for (File file : markdownFiles) { + try { + String displayName = getDocumentName(file); + String fileName = displayName + ".html"; + System.out.println(MessageFormat.format(" {0} => {1}", file.getName(), fileName)); + InputStreamReader reader = new InputStreamReader(new FileInputStream(file), Charset.forName("UTF-8")); + String content = MarkdownUtils.transformMarkdown(reader); + if (displayName.equalsIgnoreCase("overview")) { + content = MessageFormat.format(content, Constants.VERSION, "gitblit-" + Constants.VERSION + ".zip", Constants.getJGitVersion(), date); + } + OutputStreamWriter writer = new OutputStreamWriter(new FileOutputStream(new File(destinationFolder, fileName)), Charset.forName("UTF-8")); + writer.write(header); + writer.write(content); + writer.write(footer); + reader.close(); + writer.close(); + } catch (Throwable t) { + System.err.println("Failed to transform " + file.getName()); + t.printStackTrace(); + } + } + } + + private static String readContent(File file) { + StringBuilder sb = new StringBuilder(); + try { + InputStreamReader is = new InputStreamReader(new FileInputStream(file), Charset.forName("UTF-8")); + BufferedReader reader = new BufferedReader(is); + String line = null; + while ((line = reader.readLine()) != null) { + sb.append(line); + } + reader.close(); + } catch (Throwable t) { + System.err.println("Failed to read content of " + file.getAbsolutePath()); + t.printStackTrace(); + } + return sb.toString(); + } + + private static String getDocumentName(File file) { + String displayName = file.getName().substring(0, file.getName().lastIndexOf('.')).toLowerCase(); + // trim leading ##_ which is to control display order + return displayName.substring(3); + } + + private static void usage(JCommander jc, ParameterException t) { + System.out.println(Constants.getRunningVersion()); + System.out.println(); + if (t != null) { + System.out.println(t.getMessage()); + System.out.println(); + } + if (jc != null) { + jc.usage(); + } + System.exit(0); + } + + @Parameters(separators = " ") + private static class Params { + + @Parameter(names = { "--sourceFolder" }, description = "Markdown Source Folder", required = true) + public String sourceFolder; + + @Parameter(names = { "--outputFolder" }, description = "HTML Ouptut Folder", required = true) + public String outputFolder; + + @Parameter(names = { "--pageHeader" }, description = "Page Header HTML Snippet", required = true) + public String pageHeader; + + @Parameter(names = { "--pageFooter" }, description = "Page Footer HTML Snippet", required = true) + public String pageFooter; + + } +} diff --git a/src/com/gitblit/Constants.java b/src/com/gitblit/Constants.java index 1b4a5188..9cf6a54f 100644 --- a/src/com/gitblit/Constants.java +++ b/src/com/gitblit/Constants.java @@ -3,6 +3,8 @@ package com.gitblit; public class Constants { public final static String NAME = "Git:Blit"; + + public final static String FULL_NAME = "Git:Blit - a Pure Java Git Server"; // The build script extracts this exact line so be careful editing it // and only use A-Z a-z 0-9 .-_ in the string. diff --git a/src/com/gitblit/wicket/resources/markdown.css b/src/com/gitblit/wicket/resources/markdown.css index ce48cefb..41bc4392 100644 --- a/src/com/gitblit/wicket/resources/markdown.css +++ b/src/com/gitblit/wicket/resources/markdown.css @@ -3,6 +3,7 @@ */ div.markdown { + line-height: 1.4em; } div.markdown h1, @@ -51,4 +52,16 @@ div.markdown code { div.markdown a { text-decoration: underline; +} + +div.markdown ul, div.markdown ol { + padding-left: 30px; +} + +div.markdown li { + margin: 0.2em 0 0 0em; padding: 0px; +} + +div.markdown em { + color: #b05000; } \ No newline at end of file -- cgit v1.2.3