Existing github projects that are to serve as the roadmaps for hamlet remain under codeontap org. These should be either migrated or recreated under the hamlet-io org, and the docs roadmap link should be updated to send to the correct org projects board.

• Create/Migrate the codeontap + plugin projects from codeontap > hamlet-io orgs
• Update docs site navbar link to point to the hamlet-io roadmaps

This ticket is to move this website from its current home at https://hamlet.io over to https://docs.hamlet.io`. This will allow us to develop a basic closed site at hamlet.io which will be used for product promotion and sales of hamlet services

This site will become the documentation site for the hamlet services with a primary focus on the hamlet deploy tool initially

Target Audience

• hamlet users
• hamlet framework developers (incl. plugins)

Missing or Incorrect Documentation

The Broken Link Checker tool has been removed from this repository as it was both not working correctly and the capability has been added to docusaurus in a recent version that appears at build time.

This ticket is to go through the current build and review any broken links. Once all are fixed, the docusaurus.config should be updated to break a build on broken links rather than provide warnings only.

Target Audience

• hamlet users
• hamlet framework developers (incl. plugins)

The CMDB schemas have already been defined with examples, however we should also include full reference schemas so CMDB authoring/maintaining is as simple as possible.

Tab elements have already been created with places for the schemas, they just need to be updated from their placeholders.

This issue will be considered completed when the following cmdb files have schemas:

• solution.json
• segment.json
• build.json
• settings.json
• credentials.json
• template.json
• stack.json
• domains.json
• tenant.json
• ipaddressgroups.json
• countrygroups.json
• account.json
• deployment_unit.json
• .json

Description

Currently its hard to find the components which are available in the schema without using a browser search

It would be nice to have an onPage menu navigation like the one introduced here.
facebook/docusaurus#475

This could be based on the anchor tag / headings added in #59

hamlet-docs is configured to use Algolia DocSearch for its search functionality. The original site was configured under a different repository and so the DocSearch web crawler is now looking at old/non-existent content.

In order to fix this, we need to submit a PR on the docsearch-configs repository, updating our own configuration. This cannot be done until we have our production domain in place.

https://github.com/algolia/docsearch-configs/blob/master/configs/hamlet.json

{
  "index_name": "hamlet",
  "start_urls": [
    "https://hamlet.io/docs/",
    "https://hamlet.io/docs/index"
  ],
  "sitemap_urls": [
    "https://hamlet.io/sitemap.xml"
  ],
  "sitemap_alternate_links": true,
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".menu__link--sublist.menu__link--active",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": "[class^='docItemContainer_'] h1",
    "lvl2": "[class^='docItemContainer_'] h2",
    "lvl3": "[class^='docItemContainer_'] h3",
    "lvl4": "[class^='docItemContainer_'] h4",
    "lvl5": "[class^='docItemContainer_'] h5",
    "text": "[class^='docItemContainer_'] p, [class^='docItemContainer_'] li"
  },
  "selectors_exclude": [
    ".hash-link"
  ],
  "conversation_id": [
    "1093114637"
  ],
  "nb_hits": 3368
}

Description

When I drafted the skeleton of the documentation site I wanted the tutorial headings to be really clear on the lifecycle of a product with hamlet. I settled on "Create", "Deploy", "Upgrade" and "Automate" because I felt they made it very clear what hamlet could do and also how a user might progress through them.

The idea is sensible but I feel we could gain more from aligning the tutorials with the top level CLI commands that are available (currently "Create", "Generate", "Manage", "Query", "Run" and "Test". It would make the documentation and the CLI more cohesive as well as make things pretty clear as to where to find documentation (and quite clear on where to put said documentation also).

I would like to discuss here whether this change makes sense for the documentation and confirm we remain happy with these CLI commands as they are. Also if there are more of these in the near future (@roleyfoley and I have discussed a "Validate" for validating a CMDB) then this would be a good time to discuss.

Description

The reference pages for each schema type are currently independant, but call on the same <HamletComponents /> React component. This was done quickly, but should be refactored to just change the state of the component and use a single page, as is the point of React.

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Along with our roadmaps, the Release Schedule references version numbers that are associated with project milestones. We will need to re-implement these milestones and align with the project roadmaps accordingly.

Expected Behaviour

When reading the reference site and I get to a Component I should be able to see the subcomponents it supports and be able to click a link to go to the Sub Component reference guide

Current Behaviour

There is no way to find the Sub Component configuration and the Key in the Component doesn't list the sub component collection

Possible Solution

When forming the schema create refs for between the sub component and component

Context

Understand all possible options for a component

the train/tram/unicycle release strategy needs to be documented (content was there in readthedocs) and linked to a calendar - preferrably something that dinasuarus offers out of the box but could be a static page.

Description

Deprecation notifications such as this should display in a highlighted manner, so as to draw attention to them.
This may involve a formalised deprecation process in the schema.

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Currently the dockerhub repository and the hamlet-io/docker-hamlet repositories contain the definitions for each of the docker image tags. As the developer guides recommend using the docker containers instead of installations from source, the developer guides should become the central location for this documentation, and the hamlet-docker repo README updated to direct users to the developer guide instead.

This should coincide with the docker image restructure in hamlet-io/docker-hamlet#21

Unlike the hamlet "getting started guide" which is intended to be beginner friendly and completed in a matter of minutes, hamlet tutorials are intended to be in-depth walk through for common use-cases. They are likely to have varying time-frames, difficulty levels and deployment costs associated with running them.

To better display this information we require a new React component that creates a table with the following information, which we can then style however we like later down the line. The intent is for the table to present the above information immediately underneath each tutorial Title in the markdown file.

The table should include cells for:

• Duration - displayed in minutes
• Cost - displayed in $$$, similar to the way Yelp does it
• Difficulty - potentially an icon for this?
• Expected prior knowledge - a list of hamlet subjects that a user should know understand prior to starting the tutorial.

Description

Some component schemas don't appear to be loading and the page hangs on an empty screen showing an empty progress bar

Examples:
https://docs.hamlet.io/reference?type=component&instance=db
https://docs.hamlet.io/reference?type=component&instance=s3

tried on other components and other reference types and they seem to work fine.

looking in the developer console I see the following error:

InternalError: too much recursion
https://docs.hamlet.io/4ac72cd7.8b6dcef0.js:1

Description

The JSONSchema files that become the reference data pages are currently slow to load due to their size, despite being stored locally. The contents should be pre-loaded immediately prior to being requested (React has a few clever ways of doing this) so that it is instantly available upon selecting the desired reference type.

Tasks

• Investigate methods for pre-loading and parsing the JSONSchema content and select one. Document decision in comments.
• Implementation of chosen method.

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Current Behaviour

The menu bar on the left flickers and disappears. The next and previous buttons stop working.

Expected Behaviour

The left menu should scroll with the page and the next and previous buttons should always work.

Possible Solution

Steps to Reproduce

1. https://docs.hamlet.io/docs/getting-started/create-cmdb
2. Scroll halfway down the page

Before implementing #20 we should go through and correct all the broken links that already exist within hamlet. We're going to setup the broken-link-checker package to do this, so may as well run the same tool now to find them.

Tool

Current Behaviour

On the hamlet homepage when the centre getting started button is clicked on a page not found error is shown.

Expected Behaviour

The user should be taken to the getting started guide .

Steps to Reproduce

1. Go to https://docs.hamlet.io/
2. Click on the centre getting started button.

Current Behaviour

Mandatory inexplicably equals false for every attribute

Expected Behaviour

It's true at least some of the time. Preferably when that is actually the case.

Possible Solution

It's probably hard coded and forgotten about in the data tables generation. This would seek out the JSONSchema "required" parameter to see which properties are required at a given level.

Steps to Reproduce

1. View the data tables.
2. Thats it.

Description

When I first browse to the reference page I get the baseline component reference. As a user I'm not really sure where this schema came from or what it is for.

Instead maybe we should have an example reference with an introduction.
Or a landing page with something like "This is the hamlet reference guide. Select the reference you would like to see from the side menu"

Missing or Incorrect Documentation

The reference data tables that parse Hamlet JSONSchema and display it for human consumption display some empty and redundant tables.

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Description

When browsing the docs reference site ( https://docs.hamlet.io/reference ) if I click on a Reference Data instance from the menu the page shows all references and doesn't take me to the reference information I selected and shows all reference data

E.g. https://docs.hamlet.io/reference?type=reference&instance=Bootstrap shows the AlertProfiles reference along with the rest of the references

Documentation Topic

Announce our engine feature with a blog post walking through what it does and how it works

Description

Introduce the cli
Walk through the install process
Talk about the different repos and components we use to keep things modular
Walk through updating an engine or selecting another one

Audience

Hamlet users

Checklist

The following locations should be reviewed for documentation

• https://docs.hamlet.io/ (everyone)
• https://help.hamlet.io (everyone)
• Applicable repository README.md (developers of Hamlet Deploy only)
• Architectural Decision Log (developers of Hamlet Deploy only)

Hamlet docs should integrate the broken-link-checker npm package into the build pipeline for the docs site, ensuring links are always working and failing a build if not.

We should manually run it over the site first, as there are quite a few of them.

Currently the Contribute returns Page Not Found, and the contributing guides are just stand-ins for actual content. We need to develop these guidelines.

• Overview page - this can contain a list of the guidelines below and be the page for the 'Contribute' link in the navbar.
• PR / Issue template for all repos
• Guide (or link to one) for the git flow we use for PRs.
• Style guide - needs to be drafted, agreed upon and published
• Overview of the various repos.

Description

JSONSchema documentation tables and examples should be updated to handle { "$ref" : "#my.reference.target"} values. They currently show up as <undefined> in the examples. In the tables they should be links to the target schema.

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Documentation Topic

Introduction to hamlet and explanation of what it does

Description

With #137 the home page of the docs is now the first page that users go to when they want to know more about hamlet. This page should provide a simple introduction to hamlet and outlines what it does and why you would want to use it.

Page on website: https://docs.hamlet.io/
Page in source code: docs/welcome.md

Audience

New users to hamlet

Creating issue ticket for discussion on the best approach.

The hamlet docs have a need for some example CMDBs (account and products seperated out) for use within the tutorials, the getting started guide and others. These CMDBs would ideally be used for as much as possible, including during a hamlet build itself to ensure that our existing documentation is always up-to-date and we aren't pushing code that breaks the way the documentation says it should work. I think it would also make sense that the same CMDBs are the ones that hamlet developers are encouraged to develop with (if they are thorough enough then we wouldn't have much need to maintain other CMDBs.

Another usage that I have thought of for such example CMDBs is in the reference docs that outline the file structure of the CMDB. As hamlet versions change, so will the structure of the CMDB inevitably. We could ensure that the docs always reflect the latest CMDB structure by using tooling such as Markdown Magic Directory Tree. With an updated build script for the docs site that cloned the CMDBs first into the docs structure, this could be pointed at them and create a tree-like display of the CMDB. Pair this with a daily CI/CD build on the example CMDB's to ensure they are always the latest structure the docs would always present the very latest CMDB structure with no effort. Granted that this would likely require a few fake files like credentials.json in order for them to actually show up, and we'd not want to be actually deploying any of those CMDBs templates however I think the effort-to-benefit ratio is high.

Currently the "Ministry of Silly Walks" CMDBs are used for this purpose and I'd be happy to reuse them here. I do think they need a clean up because I'm pretty sure that I've made a mess of things there since working on the project. This does give us the opportunity to come up with something hamlet related to use as the topic for all of the example CMDBs too.

Feature Request

Each PR to Master should perform a BrokenLinkChecker run against it and validate there are no broken links.

Target Audience

• hamlet users
• hamlet framework developers (incl. plugins)

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Missing or Incorrect Documentation

Some reference data that should result in its own datatable is not displaying its own table configuration - only the parent heading.
An example of this is the DataFeed component schema at DataFeed.Bucket.Include.Order - it is displaying in the JSON example but there is no table displaying the "include" object structure. This is likely an issue with the implementation of recursion over the attribute structure.

Issue Checklist

• Added Issue to the hamlet roadmap project.
• Assigned the appropriate Issue labels.

Documentation Topic

Show the changes we have made to our build/test processes by discussing our CI approach and our migration

Description

Outline how we used to run on Jenkins
Outline the running hamlet container to build hamlet container issue
Outline how it works with engines
Show the CI process and testing performance updates

Audience

potential hamlet users

Checklist

The following locations should be reviewed for documentation

• https://docs.hamlet.io/ (everyone)
• https://help.hamlet.io (everyone)
• Applicable repository README.md (developers of Hamlet Deploy only)
• Architectural Decision Log (developers of Hamlet Deploy only)

Expected Behaviour

I can see a list of all blog posts that have been published along with their publish data

Current Behaviour

The blog page shows all the posts but as full pages rather than summaries. This makes it hard to see what blogs are available and requires you to scroll through a lot of pages before they come up

Possible Solution

This could be a bug where we need to include a summary point in the posts to reduce the size of each blog in the main page ( https://docs.hamlet.io/blog ) or we need to add a page with summary, title and publish date

Context

The main context here is to make sure our blog posts are visible and discoverable by users

Feature Description

As the place with the greatest potential for confusion when first getting started with hamlet, the reference data documentation for hamlet components that can defined in a users CMDB should be as clear and understandable as possible. The more assistance we can offer a user in identifying the correct design of their desired component the better.

Within hamlet itself, each component is defined and verified by its own schema. This schema is soon to be converted into JSON schema format and the build process of hamlet will be updated to publish a copy of each resources JSON schema into this docs repository. It is from those jsonschema definitions that our Component Reference docs should be defined, so as to ensure that the documentation is always in alignment with the product.

Feature Definition

In order to accomplish this a new docusaurus Page should be created, that renders the content of the JSONSchema files into a human-readable format. This will require a new React component for HamletReferences that should import all JSON Schema files in a given directory (also required to be defined), then return all of them in the desired manner.

For each component schema discovered, the output should look as follows:

1. Component heading.
2. Component description.
3. Any sub-components that are defined with corresponding definitions.
4. A 4+-tabbed multi-language code block Component with code tabs defined below.
5. Attribute Reference for attributes, sub-attributes etc. within the Schema. This should be below the multi-language code block, so as the user can read attribute definitions and review their chosen tab of the Schema at-will. These should also be expandable options so as to be able to review the desired attribute and its location on the Schema simultaneously on an average computer monitor.

Any new React components required for this implementation should live under /src/components so as to keep the /src/pages/ directory tidy.

Code Tabs

• Schema - JSON Format - codeblock that shows the outline of the component schema. These should look the same as the codeblocks already displayed on our existing reference page.
• Schema - YAML Format - this should be the same as the previous tab, except defined in YAML. The YAML will not be defined within the schema, it should be translated on the fly by additional means.
• Designer - splitting the tab into two vertically, the left-hand side should offer text-fields to the user for each Attribute, and the right hand side should display the schema-conforming object. The output should be swap-able between JSON and YAML at will.
• Examples - The JSON Schema will define one or greater examples, and for each example there should be an additional tab showing this example in a code block. This will allow us to offer simple and complex examples as required per component.

All of these tabs should include a click-to-copy feature. This is an out-of-the-box feature of the existing multi-language code block tabs, however should something else end up being used this feature should remain.

Though this new page will be a docusaurus "Page" (a React page), it should appear to users to be a part of our "Docs" section. As such it will need to be referenced using a Link in sidebar.js i.e:

{
      type: 'category',
      label: 'Reference',
      items: [
        {
          type: 'category',
          label: 'CMDB',
          items: [
            'reference/cmdb/cmdb-folder-structure-01',
            'reference/cmdb/cmdb-folder-structure-02'
          ]
        },
        {
          type: 'link',
          label: 'Component Ref',
          href: '../../../components'
        },
        'reference/glossary',
      ]
}

Schema Structure
Currently the Schema export from hamlet is still being implemented, however development on this can proceed based on the following Schema structure.

Deployed preproduction schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "http://hamlet.io/schema/latest/blueprint/component.json",

    "definitions": {

      "deployment-units" : {
        "type" : "array",
        "items" : {
          "type" : "string"
        }
      },

      "instances" : {
        "type" : "object",
        "additionalProperties": true,
        "properties": {
          "Versions" : {
            "type" : "object",
            "additionalProperties": true
          }
        }
      },

      "s3": {
        "type": "object",
        "properties": {
          "Instances" : { "$ref": "#/definitions/instances" },
          "DeploymentUnits" : { "$ref" : "#/definitions/deployment-units" },
          "Lifecycle": {
            "type": "object",
            "additionalProperties" : false,
            "properties": {
              "Expiration" : {
                "description": "Provide either a date or a number of days",
                "type" : [ "string", "number" ]
              },
              "Offline" : {
                "description" : "Provide either a date or a number of days",
                "type" : [ "string", "number" ]
              },
              "Versioning" : {
                "type" : "boolean",
                "default" : false
              }
            }
          },
          "Website" : {
            "type" : "object",
            "additionalProperties" : false,
            "properties": {
              "Index" : {
                "type" : "string",
                "default" : "index.html"
              },
              "Error" : {
                "type" : "string",
                "default" : ""
              }
            }
          },
          "PublicAccess" : {
            "type" : "object",
            "patternProperties": {
              "^[A-Za-z_][A-Za-z0-9_]*$" : {
                "type" : "object",
                "additionalProperties" : false,
                "properties": {
                  "Enabled" : {
                    "type" : "boolean",
                    "default" : false
                  },
                  "Permissions" : {
                    "type" : "string",
                    "enum": [ "ro", "wo", "rw"],
                    "default" : "ro"
                  },
                  "IPAddressGroups" : {
                    "type" : "array",
                    "items": {
                      "type" : "string"
                    },
                    "default" : [ "_localnet"]
                  },
                  "Paths" : {
                    "type" : "array",
                    "items": {
                      "type" : "string"
                    },
                    "default" : []
                  }
                }
              }
            }
          },
          "Style" : {
            "description": "TODO(mfl): Think this can be removed",
            "type" : "string"
          },
          "Notifications" : {
                "type" : "object",
                "patternProperties": {
                  "^[A-Za-z_][A-Za-z0-9_]*$" : {
                    "type" : "object",
                    "additionalProperties" : false,
                    "properties": {
                      "Prefix" : {
                        "type" : "string"
                      },
                      "Suffix" : {
                        "type" : "string"
                      },
                      "Events" : {
                        "type" : "array",
                        "default" : [ "create" ],
                        "items" : {
                          "type" : "string",
                          "enum": [ "create", "delete", "restore", "reducedredundancy"]
                        }
                      }
                    }
                  }
            },
            "additionalProperties": false
          },
          "additionalProperties" : false
        }
      },

      "template" : {
        "type" : "object",

        "properties": {
          "Instances" : { "$ref": "#/definitions/instances" },
          "DeploymentUnits" : { "$ref" : "#/definitions/deployment-units" },
          "RootFile" : {
            "type" : "string",
            "description": "The name of the root template file in the build aretefact"
          },
          "Fragment" : {
            "type" : "string"
          },
          "Parameters" : {
            "type" : "object",
            "patternProperties": {
              "^[A-Za-z_][A-Za-z0-9_]*$" : {
                "additionalProperties" : false,
                "type" : "object",
                "properties": {
                  "Key" : {
                    "type" : "string"
                  },
                  "Value" : {
                    "type" : "string"
                  }
                },

                "required": [ "Key "]
              }
            }
          },
          "Attributes" : {
            "type" : "object",
            "patternProperties" : {
              "^[A-Za-z_][A-Za-z0-9_]*$" : {
                "additionalProperties" : false,
                "type" : "object",
                "properties" : {
                  "TemplateOutputKey" : {
                    "description": "The name of the template output you want to map to an attribte",
                    "type" : "string"
                  },
                  "AttributeType" : {
                    "description": "The output type to map the attribute with",
                    "enum": [ "dns", "arn", "url", "name", "ipaddress", "key", "port", "username", "password", "region"],
                    "type" : "string"
                  }
                },

                "required" : [ "TemplateOutputKey", "AttributeType" ]
              }
            }
          },
          "NetworkAccess" : {
            "type" : "boolean",
            "default" : false
          }
        },
        "additionalProperties": false,

        "required": [ "RootFile"]
      }

    },

    "type": "object",

    "patternProperties": {
      "^[A-Za-z0-9_-]*$" : {
        "properties": {
          "s3" : { "$ref" : "#/definitions/s3"},
          "template" : { "$ref" : "#/definitions/template"}
        },
        "additionalProperties": true
      }
    },

    "additionalProperties" : false
}

For examples of existing implementations of the multi-language code blocks, please see:

• existing reference page
• docs markdown

Documentation Topic

Add details on updating and checking for the required hamlet cli verison as part of the how to guide

Description

Following on from #160 there is an issue where the current docker image for hamlet is running an old version of the cli. We should add a minimum version of the hamlet cli and engine to use for the getting started guide and include this as part of the installation process

Audience

New users to hamlet

Checklist

The following locations should be reviewed for documentation

• https://docs.hamlet.io/ (everyone)

Description

After merging the schema instance changes in #90 the github action which updates the schema pages seems to be failing

See https://github.com/hamlet-io/docs/runs/1867667325?check_suite_focus=true

Description

Currently the component type loads next to the example of the schema, from a presentation perspective it might look better as a heading maybe a H2/H3 heading.

This would also it to be provisioned as an anchor tag for deep linking to different schema components

Currently the docs reference appsettings.json which in the latest CMDB structure is just 'settings.json'.

There are likely other CMDB layout references that are outdated. It should be revisited to ensure accuracy, and then will be little effort to ensure its up-to-date.

Currently the Reference data for components is still in a state that was to display the design of the docs site. The formatting for all components needs to be updated on the "Attribute Reference" tab. Currently it is formatted to display hyperlinks to old content. The hyperlinks need to be removed and a more easily read format provided - perhaps a markdown table.

Expected Behaviour

When using the docs site I can search for content in the reference docs and get results back

Current Behaviour

Reference data isn't included as part of the site search

Possible Solution

Context

The reference is a useful store of information that people would search for the most. This is a good jump off point for people who come across hamlet deployments in the wild

Documentation Topic

Announce our support for windows based ec2 instance support with a blog post outlining what it does and how it works

Description

Brief intro the compute tasks
Demo on how easy it is to switch the ec2 component from awslinux to windows

Audience

Hamlet users

Checklist

The following locations should be reviewed for documentation

• https://docs.hamlet.io/ (everyone)
• https://help.hamlet.io (everyone)
• Applicable repository README.md (developers of Hamlet Deploy only)
• Architectural Decision Log (developers of Hamlet Deploy only)

Hello Hamlet team,

I saw that your Docusaurus project has plenty of JSON Schema on https://github.com/hamlet-io/docs/tree/master/static/schema/latest

Would your project be interested to show your JSON schema(s) to your users in a visual way ?

Here is a possible example from the schema you used on https://docs.hamlet.io/reference?type=Layer&instance=Account :

It is coming from a Docusaurus plugin called docusaurus-json-schema-plugin .

Obviously, just a suggestion ;)