Techstack : In-depth

Introduction

Harbormaster improves on the concept of a technology stack with an implementation called a Technology Stack Package (Package). 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 that are the possible result of even a single entity model.

Learn more about the growing list of supported tech stacks

Format

A package is a ZIP file containing all the mandatory and optional files that comprise the instantiation of a conceptual tech stack.

Declaration

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:

<tech-stack-package
name="Angular8 MongoDB"
shortName="Angular8"
description="Uses Angular8 with MongoDB and Mongoose"
icon-url="./img/angular8.png"
info-page-url="http://www.harbormaster.com/infopages/angularjs-mongodb-info-page.html"
version="1.0"
app-type="mobile"
release-status="alpha"
supportsDocker="true"
derivedFrom="Angular7">

Mappings

FileName Required
mappings.properties Yes

Synopsis

This required file tells Harbormaster the directory location to output 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 for the sake of a coding convention, the build process, application deployment, etc.

Configuration

FileName Required
options.xml No, but recommended

Synopsis

This file contains the options 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.

Options are normally modifiable, and often contain a default value per the author of the package. Option values can be provided in the Project-as-Code YAML or assigned within the web client.

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 pertaining to a specific tech stack.  

Templates

Synopsis

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.

Harbormaster ingests package template files and processes them using the Apache Velocity Template Engine.

A Velocity template file uses very easy familiar syntax. During generation time, Harbormaster makes available a standardized internal version of the business model along with a few helper classes, giving complete programmatic flexibility and control over what gets generated.

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 header, etc..
  • the loaded business model including each business entity, its data, methods, and associations
  • the current business entity being processed by Harbormaster

Apache Velocity Context

Velocity provides a context where objects can be shared by Harbormaster with a template file. The following objects are critical:

  • $classObject – provides access to the current ClassObject being processed by Harbormaster. Click here to explore the interface for ClassObject.
  • $aib – this object gives access to the entire business model along with helper functions to navigate the business model. Also, this object gives access to the project options and values provided for this project generation cycle. Click here to explore the interface.

Package The Stack

Once the mandatory files of the package have been created, as well as the many template files of the package, zip them into a single 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