•  

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	alpha, beta, production
app-type	string	To help a user understand the type of applications that result from using this package for project generation	yes	webapp serverless restfulapi microservice mobil other
product-line	string	A product grouping designation for the package.	No	WebApp Blockchain Blockchain Microservice Serverless AI IoT 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	true false
value	the inital value to assign
type	the field type, useful in displaying the field	input boolean select textarea spinner
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