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).

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