Introduction

With BootHub you can bootstrap your projects by generating skeletons based on various templates.

BootHub provides both a web interface and a command-line interface (CLI).

The source code is available on GitHub and is licensed under the Apache-2.0 license.

User guide

The following guidelines apply to both the web interface and the CLI.

After selecting the template on which your project should be based, you can choose whether the generated project should be created on GitHub or offered as a zip file for download.

In both cases, you will also have to provide the name of your GitHub account and the owner of the project (which can be either your user account or one of your GitHub organizations). However, if you opted for having a zip file, BootHub will not ask for your GitHub credentials and will not verify the existence of the provided GitHub account and/or organization.

If you want your project on GitHub but don’t want to give BootHub access to your account, just choose the zip file option. Later, you can easily add yourself the project to GitHub.

BootHub will then start collecting the information needed to configure your project. While most of the required pieces of information depend on the chosen template, BootHub will always ask for the following data:


Repository name: my-project
Project name [my-project]:
Project page URL [https://github.com/myuser/my-project]: https://myproject.example.org

By default, the project name is the same as the name you provide for the GitHub repository. For the project page URL, the default value suggested by BootHub links to the corresponding GitHub project page.

Most templates require to specify a license for your project:


License:
   1: The Apache Software License, Version 2.0
   2: The BSD 2-Clause License
   3: The BSD 3-Clause License
   4: The Common Development and Distribution License
   5: The Do WTF You Want To Public License, Version 2
   6: The Eclipse Public License v1.0
   7: The GNU General Public License Version 2
   8: The GNU General Public License Version 3
   9: The GNU Lesser General Public License Version 2.1
  10: The GNU Lesser General Public License Version 3.0
  11: The MIT License
  12: The Mozilla Public License Version 2.0
  13: The Unlicense
Enter your choice: 1


Also, most templates require to specify the version of your project:


Major version number [1]: 0
Minor version number [0]: 1
Patch version number [0]: 2


The remaining data required to configure the project are template-specific and are usually described in the template documentation.

Developer guide

You need Java 8 or newer in order to use BootHub.

BootHub is available in Maven Central and JCenter.

Maven
<dependency>
    <groupId></groupId>
    <artifactId>boothub-core</artifactId>
    <version>1.1.2</version>
</dependency>
<dependency>
    <groupId></groupId>
    <artifactId>boothub-db</artifactId>
    <version>1.1.2</version>
</dependency>
<dependency>
    <groupId></groupId>
    <artifactId>boothub-gradle-test</artifactId>
    <version>1.1.2</version>
</dependency>
<dependency>
    <groupId></groupId>
    <artifactId>boothub-heroku</artifactId>
    <version>1.1.2</version>
</dependency>
<dependency>
    <groupId></groupId>
    <artifactId>boothub-postgres</artifactId>
    <version>1.1.2</version>
</dependency>
<dependency>
    <groupId></groupId>
    <artifactId>boothub-web</artifactId>
    <version>1.1.2</version>
</dependency>
Gradle
compile ':boothub-core:1.1.2'
compile ':boothub-db:1.1.2'
compile ':boothub-gradle-test:1.1.2'
compile ':boothub-heroku:1.1.2'
compile ':boothub-postgres:1.1.2'
compile ':boothub-web:1.1.2'

Command Line Build

BootHub is built with Gradle and requires JDK 8 or higher. Clone the GitHub repository, cd into the top directory and start the build:

git clone https://github.com/boothub-org/boothub.git
cd boothub
./gradlew clean build            (On Windows: gradlew clean build)

IntelliJ Idea

  • start the IntelliJ Idea IDE

  • make sure that the Groovy plugin is enabled

  • open build.gradle

Eclipse

  • start the Eclipse IDE

  • install the Groovy plugin

  • install a recent version of Buildship

  • import the project using the Gradle Project wizard

Upload to Bintray

The Bintray credentials must be available in a file called gradle-local.properties. You can use gradle-local.template.properties as template and adjust it accordingly.

Writing BootHub templates

Instead of writing a BootHub template from scratch, it is recommended to use one of the following approaches:

  • generate a template skeleton using the Meta-Template.

  • copy an existing template that is somewhat similar to the one you want to write and then adjust it to your needs.

Template structure

The structure of a BootHub template is shown in the figure below:

template structure

The directories files and files-src contain file templates that will be processed by BootHub to generate a project skeleton. The generation is guided by a series of control files in accordance with the project context. The next sections describe this process in detail.

Template info

Each template provides information about itself. The file info.yml contains structured information (such as name, id, version, homepage), while description.md provides a markdown description of the template’s purpose and capabilities.

The Boothub GUI displays this information in an aggregated form as shown in the image below:

java groovy info

The markdown description uses the CommonMark format and should contain only 'safe' elements. Raw HTML and potentially unsafe URLs in links and images (those beginning with javascript:, vbscript:, file: etc.) are not rendered.

Project context

Before generating a project skeleton, BootHub collects template-independent and template-specific data. These are used to populate the project context, which contains properties needed to customize the project skeleton.

A project context is an instance of org.boothub.context.ProjectContext. Simple templates can directly use this class, but usually a subclass of ProjectContext is needed. You specify the class required for your project context in the file config.yml.

The standard way to extend ProjectContext or one of its existing subclasses is to implement additional traits. Each trait adds one or more properties to the project context.

The diagram below shows available traits, ProjectContext subclasses and other related classes. Traits are colored blue.

project context

Looking at the bottom of the above image, you can see that BootHub provides a series of ProjectContext subclasses (with names of the form StandardProjectContext.TemplateType), which help you create the appropriate project context for your template. They are useful if your template should generate projects that produce Maven-compatible artifacts (jar, war, ear etc.).

In general, your template needs one or more specific properties that are not provided by the existing ProjectContext subclasses. Therefore, you need to create a custom project context class for your template. This involves the following steps:

  • create one or more custom traits that provide the additional properties needed by your template.

  • choose a suitable base class for your project context class.

  • create your custom project context class that extends the chosen base class and implements your custom traits.

The above mentioned traits and classes must be implemented in Groovy and placed in the script directory.

The Meta-Template does a good job in choosing a suitable base class for your project context depending on the options you choose during the template skeleton generation. It also creates a custom project context class implementing a sample trait with a sample property.

Each trait implemented by your project context class must have an associated configurator class, which you specify using the ConfiguredBy annotation.

To exemplify, let’s look at the project context of the Java/Groovy template, which is implemented by the JavaGroovyProjectContext class, as specified in the configuration file:

template/config.yml
contextClass: org.boothub.context.JavaGroovyProjectContext

In order to be properly configured, some of the features provided by the Java/Groovy template require additional properties. These properties are provided by a series of feature-specific traits implemented by the JavaGroovyProjectContext class:

template/script/org/boothub/context/JavaGroovyProjectContext.groovy
package org.boothub.context

class JavaGroovyProjectContext
    extends StandardProjectContext.Generic
    implements LanguageContext,
               TestFrameworkContext,
               BintraySupport,
               DocPublishing,
               AsciiDocSupport,
               LicenseCheckSupport,
               FindbugsSupport,
               CloverSupport {
}

The CloverSupport trait provides a boolean property that indicates whether the Gradle script of the generated project should add support for code coverage with Clover.

template/script/org/boothub/context/CloverSupport.groovy
package org.boothub.context

import groovy.transform.SelfType
import org.beryx.textio.TextIO

@SelfType(ProjectContext)
@ConfiguredBy(CloverSupport.Configurator)
trait CloverSupport {
    boolean useClover = true

    static class Configurator extends TextIOConfigurator  {
        @Override
        void configureWithTextIO(ProjectContext context, TextIO textIO) {
            def ctx = context as CloverSupport
            ctx.useClover = textIO.newBooleanInputReader()
                    .withDefaultValue(ctx.useClover)
                    .read("Use Clover?")
        }
    }
}

Note how the @ConfiguredBy annotation is used to specify the configurator class associated with this trait.

The configurator class provides the code necessary to configure the trait properties. Usually, the properties values are obtained interactively from the user. In order to allow BootHub to run the configurator code both in the CLI and the web interface, all input/output operations required by a configurator should be implemented using the Text-IO library.

Template processing

BootHub uses the handlebars.java template engine to process the following files:

  • regular files and their control file files.yml

  • module source files and their control file sources.yml

  • the usage instructions file instructions.md

The tags in the above mentioned documents are expanded using the values of the properties provided by the project context.

Additionally, for each module source file BootHub creates a SourceFileContext whose properties are also used during tag expansion. See Module source files for more details.

The following helpers can be accessed in the documents processed by the handlebars template engine: Handlebars.java Helpers, StringHelpers and BootHub’s Helpers.

Regular files

Regular files reside in the files directory (or in its subdirectories) and are controlled by the files.yml file, which configures a list of FileContexts.

A FileContext instance is characterized by three properties that tell BootHub how to handle a particular file:

  • String filePath (mandatory) - the path of the source file relative to the template directory. If the file is located directly under the template directory, the filePath contains only the file name. Otherwise, it has the format subdirectory/fileName.

  • String targetPath (optional) - the destination path relative to the target directory. If missing, the filePath value will be used.

  • boolean enabled (optional) - whether this file should appear in the generated project skeleton. Default value: true.

For example, the following entry can be found in the files.yml of the Java/Groovy template:

--- !!org.boothub.context.FileContext
filePath: settings.gradle
enabled: {{multiModule}}

This means that the file settings.gradle located directly under the template directory should appear in the generated skeleton only if a multi-module project is desired. Since no targetPath is specified, the file will retain its original name and relative location.

The content of settings.gradle is shown below:

rootProject.name = '{{ghProjectId}}-root'

String[] modules = [
    {{~#each modules}}
    '{{artifact}}',
    {{~/each}}
]

include modules

If a regular file doesn’t have a corresponding FileContext entry in files.yml, it will appear unconditionally in the generated project, retaining its original name and relative location.

Module source files

Module source files reside in the files-src directory. They are needed for Maven-compatible project skeletons, which consist of one or many modules, where each module usually produces an artifact.

Each module is described by a SourceContext configured in the sources.yml file. Each SourceContext contains the name of the artifact produced by its corresponding module and a list of SourceFileContexts associated with this module.

A SourceFileContext instance is characterized by the following properties that tell BootHub how to handle a particular source file:

  • String fileName (mandatory) - the name of the source file.

  • String targetBaseDir (optional) - the base directory of the target file relative to the module path. Default value: empty string.

  • String targetPackage (optional) - the package of this source file. Default value: empty string. BootHub will place the target file in a subdirectory corresponding to the targetPackage in the targetBaseDir.

  • String targetFileClass (optional) - the name of the class defined by this source file. If missing, the class name is set in accordance with the fileName.

  • boolean enabled (optional) - whether this source file should appear in the current module. Default value: true.

Below you can see a fragment of the sources.yml file of the Java/Groovy template:

{{#each modules}}
--- !!org.boothub.context.SourceContext
artifact: {{artifact}}
fileContexts:
    - !!org.boothub.context.SourceFileContext
      fileName: JavaMain.java
      targetBaseDir: src/main/java
      targetPackage: {{basePackage}}
      targetFileClass: {{appMainClass}}
      enabled: {{and useJava (not useGroovy) appMainClass (compare artifact '==' appModule.artifact)}}

    - !!org.boothub.context.SourceFileContext
      fileName: JavaUtil.java
      targetBaseDir: src/main/java
      targetPackage: {{basePackage}}
      targetFileClass: {{artifactAsClassName}}JavaUtil
      enabled: {{and useJava (or useGroovy (not appMainClass) (compare artifact '!=' appModule.artifact))}}

    # ...
    # more SourceFileContext entries...
    # ...

{{/each}}

For simplicity, the example above contains only two of the SourceFileContext entries present in the actual sources.yml file.

The handlebars tags will be replaced with the values of their corresponding project context properties during the template processing. The useJava and useGroovy are specific to the Java/Groovy template, while the other ones are common properties you can find in the project context diagram.

Note that the handlebars processing of the above sources.yml file will produce a SourceContext for each module present in the project context. For pure Java projects the JavaMain.java source file is enabled only for the application module, while JavaUtil.java is enabled for the other modules.

Note also that these two source files will have custom names in the generated project, since a targetFileClass is specified for them.

The content of JavaMain.java is shown below:

\{{javaComment 'license-header.txt'~}}
package {{targetPackage}};

public class {{targetFileClass}} {
    public static void main(String[] args) {
        System.out.println("Hello from {{targetFileClass}}!");
    }
}

Source files are processed twice by Handlebars: first time using their corresponding SourceFileContext and then using the project context.

Note the \{{ at the beginning of the first line in the JavaMain.java template. The \ prevents Handlebars from handling the javaComment tag during the first processing step (with the SourceFileContext). Instead, it will be handled during the second processing step (with the project context).

Usage instructions

After generating a project, the BootHub web interface processes the markdown content found in the file instructions.md in order to display usage information related to this project:

The markdown description uses the CommonMark format and should contain only 'safe' elements. Raw HTML and potentially unsafe URLs in links and images (those beginning with javascript:, vbscript:, file: etc.) are not rendered.

License files

By default, BootHub provides 13 software licenses to choose from.

You can provide additional licenses for your template in the template/licenses directory. For each additional license you need to create a subdirectory whose name represents the licenseId. In this subdirectory you should place three files:

  • LICENSE - contains a plain-text copy of the license

  • license-header.txt - contains a short license header that should usually be included at the top of each source file.

  • license.yml - a YAML file that configures the license name and, optionally, a URL to the license text.

For example, if your template additionally provides the Artistic license 2.0, the following license.yml file should be present in the template/licenses/Artistic-2.0 directory:

template/licenses/Artistic-2.0/license.yml
licenseName: The Artistic License 2.0
licenseUrl: http://www.perlfoundation.org/attachment/legal/artistic-2_0.txt

BootHub adds the properties configured in license.yml to the project context.

BootHub reads the content of the license.yml file associated with the license type chosen by the user and adds each entry to the ext property of the project context. Therefore, you can include these values in any file processed by the template engine by using the tags {{ext.licenseName}} and {{ext.licenseUrl}}.

Publishing your templates

  • create a zip file with the content of the skeleton directory.

  • put this zip file on a location that is directly accessible by http or https.

  • go to the Template Manager tab of the web interface, enter the URL of your zipped template and click the Add template button.

Example:

The Java/Groovy template is hosted on GitHub. A zip file of its skeleton directory is attached to each release, therefore it is directly accessible via http(s).

The Java/Groovy template with version 1.0.0 has been published by entering the following URL in the Template Manager tab of the web interface:
https://github.com/boothub-org/boothub-template-java-groovy/releases/download/v1.0.0/java-groovy-1.0.0.zip

Installing BootHub on-premises

Some of the reasons to install your own BootHub web server are:

  • you want to use your own template repository, which may include proprietary / closed-source templates.

  • you want to be able to generate project skeletons on your private GitHub organizations.

  • you are behind a firewall and cannot use the standard BootHub web interface.

Installing the binaries

From the releases page download the boothub-web-1.1.2.zip file and unpack it into a directory of your choice.

Before starting the server, you need to setup the GitHub authentication and to configure your BootHub server.

OAuth configuration

In BootHub there are two actions that require authentication:

  • generating a project skeleton on GitHub: this requires read/write access to your repositories and organizations. We denote this scenario as repo authentication.

  • managing templates: in this case, BootHub only needs to check your GitHub identity. You don’t grant any access to your repositories or organizations. We denote this scenario as info authentication.

For each of the two use cases you need to create an OAuth App on GitHub. Sample values for the properties of your OAuth apps are given in the table below:

OAuth property

Sample value

Repo authentication

Info authentication

Application name

MyBootHub

MyBootHubInfo

Homepage URL

http://myboothub.example.org

http://myboothub.example.org

Application description

Skeleton generation

Template management

Authorization callback URL

http://localhost:8080/app/callback

http://localhost:8080/info/callback

After creating an OAuth app, GitHub displays the generated Client ID and Client Secret:

Client ID
1a2b3c4d5e6f1a2b3c4d

Client Secret
1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1a2b

The BootHub server needs to know the details of your OAuth apps. You can provide this information via configuration files and/or environment variables. Environment variables take precedence over properties specified in configuration files.

Repo OAuth configuration

If a file called boothub-oauth.cfg exists in the current directory, BootHub reads its content (you can use boothub-oauth.template.cfg as template). The table below shows the available configuration properties and their corresponding environment variables:

Property Environment variable Sample value Description

name

BOOTHUB_OAUTH_NAME

MyBootHub

The application name of your Repo-OAuth app.

scope

BOOTHUB_OAUTH_SCOPE

public_repo read:org

One or more OAuth scopes separated by blanks.

callbackUrl

BOOTHUB_OAUTH_CALLBACK_URL

http://localhost:8080/app/callback

The callback URL of your Repo-OAuth app.

key

BOOTHUB_OAUTH_KEY

1a2b3c4d5e6f1a2b3c4d

The client ID you received from GitHub for your Repo-OAuth app.

secret

BOOTHUB_OAUTH_SECRET

1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1a2b

The client secret you received from GitHub for your Repo-OAuth app.

Info OAuth configuration

If a file called boothub-info-oauth.cfg exists in the current directory, BootHub reads its content (you can use boothub-info-oauth.template.cfg as template). The table below shows the available configuration properties and their corresponding environment variables:

Property Environment variable Sample value Description

name

BOOTHUB_OAUTH_INFO_NAME

MyBootHubInfo

The application name of your Info-OAuth app.

callbackUrl

BOOTHUB_OAUTH_INFO_CALLBACK_URL

http://localhost:8080/info/callback

The callback URL of your Info-OAuth app.

key

BOOTHUB_OAUTH_INFO_KEY

1a2b3c4d5e6f1a2b3c4d

The client ID you received from GitHub for your Info-OAuth app.

secret

BOOTHUB_OAUTH_INFO_SECRET

1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4d5e6f1a2b

The client secret you received from GitHub for your Info-OAuth app.

Server configuration

The BootHub server supports configuration files defined in the form of Groovy scripts accepted by a ConfigSlurper.

The following steps are performed in order to read the configuration:

  • if the environment variable BOOTHUB_WEB_APP_CFG is set, then its value is taken to be the configuration location.

  • otherwise, the configuration location takes the default value boothub-web-app.cfg.

  • if a file exists on the file system at the configuration location, its content is read.

  • otherwise, if a Java resource is available at the configuration location, its content is read.

  • otherwise, BootHub uses default values for all properties.

The table below shows the properties you can provide in a configuration file:

Property Type Default value Description

port

int

8080

The HTTP(S) port on which the server runs.

outputDirBasePath

String

the value of the java.io.tmpdir system property

the base directory used for generating skeleton files.

zipFilesBasePath

String

the value of the java.io.tmpdir system property

the base directory used for generating zipped skeletons.

browserAutoStart

boolean

false

if true, the main application page will be automatically opened in a browser after the server started.

repoManager

RepoManager

HSQLDBRepoManager

the repository manager (see details below).

The repository manager

Your server uses its own template repository, which is usually backed by a database. In order to access this template repository, a repository manager is needed. BootHub offers a few implementations of RepoManager, which are shown in the table below. You can also write your own implementation, if none of the existing ones meet your needs.

Class Sample configuration Comments

HSQLDBRepoManager

boothub-web-app.hsqldb.cfg

Manages a HSQLDB template repository.
Typically used when running a single-user BootHub server.

PostgresRepoManager

boothub-web-app.postgres.cfg

Manages a PostgreSQL template repository.
Best suited when the BootHub server is used by a group of developers.

HerokuPostgresRepoManager

boothub-web-app.heroku.cfg

Manages a PostgreSQL template repository on Heroku.
Used when the BootHub server is hosted on Heroku and uses the Postgres add-on.

ReadOnlyJsonRepoManager

boothub-web-app.json.cfg

Can read BootHub templates from a JSON template repository but cannot perform any changes on it (all operations under the Template Management tab will fail).
Typically used with the standard template repository when you don’t have your own templates but you need your own BootHub server because you want to access your private GitHub organizations or because you don’t trust the publicly available BootHub server.

If you use a repository manager for a database-backed template repository and the repository does not yet exist, an empty one will be created. Then, you can publish your templates to this repository. See Publishing your templates for more details.

Starting the server

Run the boothub-web script in the bin directory of your unpacked binaries.