Publish Your Reference Application
Table of Contents
Introduction
You likely have one or more applications you have written that can serve as a reference for applications not yet written. When that reference application becomes reusable, it simplifies your life because you can easily create new applications with a full understanding of all aspects of that application. This not only will speed up your delivery and cut costs significantly, it will improve the quality of all your projects that are based on the single reusble reference application.
The term techstack is often used in place of reference application. They both capture the concept of all the components of a project.
The following sections detail how to take an existing reference application, make it reusable, then package and publish it to Harbormaster for future project generation use.
Details
Harbormaster improves on the concept of a technology stack with an implementation called a Technology Stack Package (referred to as Package or Reference Application).
A Package not only includes all the concepts of a bundled technology stack, it also includes the template-driven abstractions, features, components, and services of a specific kind of application.
Being template-driven is crucial to a package since it is the active tier between a technology stack and a business model. Importantly, a package can accommodate an endless combination of technologies and application features. Equally important is that a single package can be bound during generation time with a countless # of models, resulting in a countless # of different projects/applications.
Learn more about our growing list of supported tech stacks.
Anatomy of a Reference Application
In order to publish a reference application to Harbormaster, it is important to understand what are the required and optional components of a reference application.
A reference application itself is published to Harbormaster as a single Zip file. Let’s take a quick look at what is inside this Zip file before learning how to build your own.
Build Your Own
A package is a ZIP file containing all the mandatory and optional files that comprise the instantiation of a conceptual tech stack.
For the most part, a techstack first started off as an example reference application but nothing says a techstack has to be related to an application. A techstack could be anything you care to define as reusable that can be bound to a domain model for a specific model-driven outcome. This level of flexibility is what differentiates Harbormaster from any other platform in the space.
Even though Harbormaster ships with a variety of pre-built techstack packages (reusable reference applications), the possibilities for a package are nearly endless. In the event you have a reference application and prefer to use it, take the following steps to turn it into a reusable techstack package:
Declare The Package
FileName | Required |
techstackpackage.xml | Yes |
Synopsis
This required file contains the mandatory and optional declarations of a package. The example below is a good illustration:
name="Axon4"
shortName="Axon4"
description="Axon Framework and Axon Server(optional), using a persistent store CQRS with a seperate store for event sourcing"
icon-url="./img/axoniq.png"
info-page-url="https://harbormaster.ai/axon-tech-stack/"
version="0.8"
release-status="beta"
app-type="restfulapi"
product-line="Microservice"
derivedFrom=".spring.boot.tech.stack"
supportsDocker="true"
supportsKubernetes="true">
Entry | Type | Description | Required | Valid Values |
---|---|---|---|---|
name | string | The readable name of the package | yes | Any unique name |
shortName | string | An abbreviated form of the name field | yes | Any unique name |
description | string | A short description of the purpose of what is contained in the package and the outcome of generating with it | yes | |
icon-url | string | The absolute or relative URL to a representative image. A square image works best, with a max of 512×512 | yes | A valid URL |
info-page-url | string | The absolute or relative URL to a web page or document that details the package including its purpose, contents, and parameters that user can apply to it during project generation | yes | A valid URL |
version | string | The version of the package, completely controlled by. This is useful in conjunction with the release-status field | yes | Any unique value |
release-status | string | The status you decide for this version of the package | yes |
|
app-type | string | To help a user understand the type of applications that result from using this package for project generation | yes |
|
product-line | string | A product grouping designation for the package. | No |
default: WebApp |
derivedFrom | string | A comma delimted list of other packages (techstacks) this one extends. Be aware that when deriving from another techstack, you understand what that techstack does, what it outputs and to where. Also, if you derive from more than one, the order of derivation decides the order of generation which in turn may have an impact on the resulting project. This is because one package can override (overwrite) the output of another during project generation. | no | |
supportsDocker | boolean | If your package, or one it derives from, needs to support Docker packaging,this is where to designate it. | no | defaults to false |
supportsKubernetes | boolean | If your package, or one it derives from, needs to support Kubernetes deployment,this is where to designate it. This is experimental | no | defaults to false |
File Ouput Mapping |
![]() |
FileName | Required |
mappings.properties | Yes |
Synopsis
This required file tells Harbormaster which directory location to output and the name to give to a generated file. During project generation, it provides the flexibility needed to separate where a template file is discovered versus where its generated output should be placed. This is critical for the sake of a coding convention, the build process, application deployment, etc.
When deriving from another techstack, it is important to understand how it maps its files
Learn more about creating a mappings.properties file.
User Input Options |
![]() |
FileName | Required |
options.xml | No, but recommended |
Synopsis
Each package likely has one or more parameters that require user input. This file contains the option declarations used to make decisions that impact project generation, having implications on how a project is generated and likely how it is built, deployed and executed. It can contain general options such as the app name, author, app logo URL. It can also contain options related to such things as AWS, Heroku, CI/CD, Docker and other target technologies your reference application uses. These options get translated by the Harbormaster WebApp and turned into HTML for user input. In this way, a package has the flexibility to define any number of inputs and input types.
Options are normally modifiable, and often contain a default value per the author of the package. Option values can also be provided in a Project-as-Code YAML for use via the Harbormaster CLI for project generation.
Here is an example of content within an options.xml file:
selections=”h2,mysql,postgres,mongodb”required=”true”description=”supported database types” type=”select”/>
Entry | Description | Valid Values |
---|---|---|
name | The unique name of the field amongst this group of fields | |
required | Is user required to enter a value for this field |
|
value | the inital value to assign | |
type | the field type, useful in displaying the field |
|
selections | the comma delimitted values to display when the type is select |
Sample Project-as-Code File |
![]() |
FileName | Required |
sample-project-as-code.yaml | Yes |
Synopsis
Serves as documentation and an example of the standard and unique directives and inputs pertaining to a tech stack.
Learn more about the components of this YAML file.
Templatizing The Package |
![]() |
Synopsis
In order for a package to have any published domain model applied to it, it must be templatized. Templatizing is the process of replacing the specifics of certain files within your techstack (reference application) with parts of the domain model and/or specific property values provided by the user.
A template is an extremely generic file, and can represent anything. That being said, each template has a real purpose towards the overall intent of the package and the project it results in. Likely, a template is a source code file, a configuration file, or any other type of file that would be found in a reference application.
A file may not have to be templatized since not all files will have its name or contents impacted by a domain model or project specific properties.
Exploring our techstack packages is the best way to see easy it is to turn any file into a templatized file.
How It Works (Highlight)
Harbormaster ingests a package’s template files and processes them one at a time leveraging the Apache Velocity Template Engine.
A template file looks like a normal project file but with Velocity directives included. Such a template file uses familiar Java-like syntax. During generation time, Harbormaster makes available a standardized internal version of the domain model along with a other helper classes, giving complete programmatic flexibility and control over what you decide gets generated. A template file can contain simple or sophisticated logic, depending upon your file generation requiremetns.
Concepts
Harbormaster provides a substantial set of Velocity macros and bound functions to give simplified access to:
- helper macros to provide consistent output of such things as a standard file header, etc..
- the loaded domain model including a collection of business entities, its data, methods, and associations
- the current business entity being processed by Harbormaster
Learn more about file templatizing and Harbormaster Project Generation
Apache Velocity Context |
![]() |
Velocity provides a context where objects can be shared between Harbormaster and a template file being processed. The following objects are critical to successfully templating a file.
var name | description | example |
---|---|---|
$classObject | Gives access to the current entity being processed by Harbormaster. Click here to review. | $classObject.getAttributes() |
$aib | This object gives access to the entire domain model along with helper functions to navigate the domain model. Also, this object gives access to the project options and values provided by the user for this project generation cycle. Click here to review. | $aib.getClassesToGenerate() $aib.getParam(“go.dbName”) |
$appName | The application name the user entered and provided as a convenience | |
$Utils | Contains helper functions to assist in manipulating data normally required for outputting within a template engine environment. Click here to review. | $Utils.lowercaseFirstLetter(${classObject.getName()}) |
$techstack | The current techstack being processed. Click here to review | $techstack.getName() |
$user | The user performing the project genration. Click here to review | $user.getFullName() |
$esc | The Apache Velocity Escape tool for escaping on certain characters. | $esc.dollar to output a dollar sign |
$math | The Apache Velocity Math tool for performing math operations. | |
$display | The Apache Velocity Display tool for formatting output. | |
$convert | The Apache Velocity Convert tool for conversion operations between data types. | |
$loop | The Apache Velocity Loop tool for iterating through collections. |
Package The Stack
Once the mandatory files of the package have been created, and the necessary files have been templatized, zip them all into a single ZIP archive file.
Publish The Stack
The new tech stack package can be published directly to the Harbormaster platform using the web app or indirectly to a Harbormaster instance using the following command from the command-line-interface:
harbormaster stack-publish ./yamls/save-my-tech-stack.yml public
Click here to learn more about the contents of the YAML file and techstack publishing from the Harbormaster CLI.exp