Synopsis

In order to successfully generate a project, Harbormaster requires 3 components.

1. A published business model
2. A published tech stack
3. Project option values

A project can publish a new business model or reuse a previously published model. Likewise, a project can publish a new tech stack or reuse a previously published one. Between the Harbormaster Dev Team and the Harbormaster Community, there is more than likely a useful tech stack already published. If not, feel free to create and publish one that will serve your needs and hopefully the community at large.

 

Declaration

Declaring a project is as simple as creating a single YAML file referred to as a “Project-as-Code” file. This file contains the declarations related to the model, tech stack, CI/CD, and other options related to the project.

project:
  model:
  techstack:
  options:

What is available in the options section is dependent on both the tech stack in use and what needs to be available to the project.

For instance, the default Angular8  tech stack uses MongoDB to store data and Mongoose as an ORM. This means mongodb parameters are required. For instance:

 mongodb: 
  server address:   localhost:27017
  database name:    angular7demo
  search size:      10
  default collection name: default_collection
  auto-increment id name: _id
  auto-increment seq name: seq
  mongooseHost:     http://localhost
  mongoosePort:     4000

Also, a project likely requires options such as Git and CI/CD parameters.

git: 
  name:        MyAngularGitHub 
  username:    xxxxxxxxxxxx
  password:    xxxxxxxxxxxx
  repository:  myAngularRepo
  tag:         latest
  host:        bitbucket.org
cicd:
  platform:    circleci 

Note: Sample project-as-code YAML files can be found here.

Execution

An easy way to execute a project generation session is via the web interface provided by the Harbormaster platform.  If access to a Harbormaster platform instance is not available, using the Harbormaster CLI is simple as well.

Assuming the Harbormaster CLI is already installed, project generation only requires providing Harbormaster with a project file.

harbormaster project_generate ./samples/yamls/generate-django-project.yml

Note: Sample project-as-code YAML files can be found here.

@Generation Time

During project generation, the following sequence of events take place.

Model Validation

Assure the model exists and is well formed

Model Transformation

The model is parsed into the Harbormaster Metamodel. This ensures a tech stack package can consistently and predictably use a model regardless of the form the original model took.

Techstack Validation

Assures the following for the techstack:

1. It exists within Harbormaster
2. It is well formed meaning the required files exists
3. If derived from other tech stacks, make sure each exists

Techstack Processing

There are 3 sub-steps to processing a tech stack

Mapping Property Parsing

Ingests the mappings.properties file of the tech stack package. This file contains declarations used to determine where to output a generated file.

Project Options Ingestion

Stores the provided project options for use during the next step, Template File Processing

Template File Processing

For each template file discovered in the tech stack package, Harbormaster passes the file to Apache Velocity to be transformed. Depending on how the file is named, Harbormaster will treat the file as a one-time occurrence or it will parse the meta-model applying the template file for each business entity. Learn more about meta-model parsing next.

Meta-Model Parsing

During this step, the meta-model is parsed by iterating over each business entity and in turn each of its attributes, declared functions and entity associations. The business entity is stored within the Apache Velocity context so it can be accessed by a template file.  

GIT Commit

If GIT is in use, Harbormaster will attempt to commit all generated project files into the target repo on the specified host using the provided credentials.

CI/CD Pipeline Execution

Harbormaster will create the appropriate pipeline YAML file for any supported CI/CD platform. If a pipeline has already been established and connected to the GIT repo (recommended), the pipeline will automatically execute the YAML file directives.

Project Archiving

Finally, the generated project files are zipped and stored on the file system. Its location, along with the associated model, tech stack, and options, are then stored in the database.  The zip file is available to be downloaded from the UI.