Skip to main content

Installing hamlet

hamlet is made up of two key parts:

  • engine looks after generating contracts that describe what you want to do, e.g. create infrastructure, draw diagrams, find the hostname of a deployment etc. This is built on Java using the apache freemarker template engine.
  • executor runs the contracts from the engine and provides the user interface to the engine. We have two executors which work together, a bash based backend along with a Python based CLI.

The CLI manages the installation of the required parts once it has been installed, but we do have some extra dependencies. This task will take you through the process of installing these dependencies. Here we've included some standard environments and included a description of what's required.

Getting Everything Installed

Docker provides a container based workflow to isolate hamlet and its dependencies. This image provides a general purpose environment with hamlet installed, and also includes a number of tools and packages that make it well suited for use within Continuous Integration pipelines.

  1. Install docker for your operating system using the official Docker guide here https://docs.docker.com/get-docker/
  2. Ensure that Docker is running. If you don't get a response from the following command, you'll need to start Docker before continuing.
docker info
  1. Once Docker is running, pull down the hamletio/hamlet container to your local desktop.
docker pull hamletio/hamlet
  1. As docker containers are ephemeral by nature, we'll need a directory on our local machine that can be used to store all of our work. In your local terminal change into a directory that works for you ( e.g. ~/hamlet ) and then make a new directory for your hamlet work.

If you intend to follow through the rest of the "getting started" guide, it's recommended you call this directory hamlet_hello!

## create a new directory
mkdir ~/hamlet_hello
  1. Start an interactive terminal inside of the hamletio/hamlet container and make the directory you created in the previous step available inside the container.

Each time you would like to return to this workspace you will just need to run the following Docker CLI command inside of a terminal window

docker run -it --rm --volume ~/hamlet_hello:/home/hamlet/cmdb hamletio/hamlet
hamlet @ ~/cmdb
└─ $

Outside of the container you can open an IDE or code-editor of choice and access your ~/hamlet directory. Any changes you make here will be reflected inside of the container at the path /home/hamlet/cmdb

Inside of the container in the terminal session, you will now have access to the hamlet CLI and the rest of the packages used to run hamlet.

  1. To check that everything is working as expected open up a second terminal window - this one won't be inside the container.

Navigate into the directory you created earlier and create a test file called text.txt

cd ~/hamlet_hello
echo "testing" > test.txt

Now back in the container's terminal session check that you can see the new file.

## ls - list information in the current directory
ls
test.txt

Confirm your setup

Now that we have hamlet installed we should confirm that everything is working as expected with a couple of tests.

  1. Make sure hamlet is installed and available from your shell. In a terminal window run:
hamlet --version

This will return the version of hamlet you have installed.

hamlet, version 9.3.0
  1. We now want to test that the individual parts of hamlet are working as expected.

Run the following command:

hamlet entrance list-entrances

You should now see the following output which confirms that hamlet is available and that it can call the engine.

  [*] no default engine set using train
  ╒════╤════════════════╤════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╕
  │    │ Type           │ Description                                                                                                                    │
  ╞════╪════════════════╪════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╡
  │  0 │ blueprint      │ Provides a detailed representation of everything in a given segment, this includes its parent, environment, product and tenant │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  1 │ buildblueprint │ Provides a given deployment unit's occurrences and their suboccurrences                                                         │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  2 │ deployment     │ Generates the required documents to deploy a given deployment unit / deployment group combination                              │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  3 │ deploymenttest │ Generates the required documents to deploy a given deployment unit / deployment group combination                              │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  4 │ info           │ Provides details on the hamlet engine and the avaiable entrances                                                               │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  5 │ loader         │ Generates a set of loader contracts which can be used to set up hamlet                                                          │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  6 │ occurrences    │ Provides the state of all occurrences within a district                                                                        │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  7 │ releaseinfo    │ Provides information for release management tasks performed by executors                                                       │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  8 │ schema         │ Provides JSON schema representations of input configuration                                                                     │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │  9 │ schemaset      │ Generates Schema Contracts that are used to generate all JSONSchema files by their data type.                                  │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ 10 │ unitlist       │ Provides details on all deployment unit | deployment group combinations                                                        │
  ├────┼────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
  │ 11 │ validate       │ Performs validation of the current Blueprint Object                                                                            │
  ╘════╧════════════════╧════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╛

This will:

  • check to see if you have an engine installed
  • if not, install it and configure the engine for the CLI
  • query the engine for entrances that the engine knows about.

We will get into some of these concepts later on, for now just ensures all the parts are set up correctly.

Now that we have hamlet installed and ready to go we can create our first CMDB.