Skip to content

Latest commit

 

History

History
134 lines (86 loc) · 4.51 KB

quick_start.md

File metadata and controls

134 lines (86 loc) · 4.51 KB

Library - Quick Start

Document information

GANTREE CONFIG VERSION LAST UPDATED
2.0 2020/03/30

Prerequisites

This tutorial assumes you have the following files/knowledge/etc.

  • Your own Gantree configuration
  • An installation of gantree-lib and it's external dependencies
  • Required environment variables exported

If any of these are unfamiliar, please consult further Gantree documentation.

Tutorial

In this guide we're going to be creating the infrastructure outlined in your Gantree configuration using the library.

Since we're not going to be using the CLI, let's make our own script called useGantree.js.

First, we're going to want to make the Gantree class from the gantree-lib package available in our script.

const { Gantree } = require('gantree-lib') // make Gantree class available

Now we want to define the file path to our Gantree configuration. You can do this however you see fit.

For the sake of simplicity, we're going to make this variable static.

Note that our variable name is only upper-case as this is considered best practice for static variables. In most other instances, you would likely use a camelCase naming scheme.

const GANTREE_CONFIG_PATH =
  '/home/<username>/<path>/<to>/<my>/<config>/<config_filename>.json'

Now let's begin writing a new async function. For this tutorial, we'll name it run.

We're also going to execute it right after it's definition.

async function run() {
  // our async code
}

run()

We're going to write the remainder of our code inside this async function.

Next, we'll instantiate a new object called 'gantree' from the imported class.

gantree = new Gantree() // instantiate a new Gantree object

Now we want to load our Gantree configuration as an object.

For this we use the returnConfig method of our gantree variable. Do not load the file in by another method.

const gantreeConfigObj = await gantree.returnConfig(GANTREE_CONFIG_PATH) // load and process Gantree configuration

We use this method instead of importing the file ourselves as it includes additional important functionality; returnConfig will read, validate and preprocess our Gantree configuration before we start using it.

Without validation, invalid configurations may result in errors during runtime or subtle/major deviations from our desired infrastructure. Furthermore, preprocessing allows for data to be transformed as necessary, such as when using references to environment variables in your Gantree configuration.

Lastly, we'll execute the syncAll() method with gantreeConfigObj as an argument. This method is responsible for creating our infrastructure and turning our instances into nodes.

await gantree.syncAll(gantreeConfigObj) // sync our infrastructure and nodes

Our final useGantree.js script should look like this

const { Gantree } = require('gantree-lib') // make Gantree available
const GANTREE_CONFIG_PATH =
  '/home/<username>/<path>/<to>/<my>/<config>/<config_filename>.json'

async function run() {
  gantree = new Gantree() // instantiate a new Gantree object
  const gantreeConfigObj = await gantree.returnConfig(GANTREE_CONFIG_PATH) // load and process Gantree configuration
  await gantree.syncAll(gantreeConfigObj) // sync our infrastructure and nodes
}

run()

In the event you've forgotten to export any required environment variables, Gantree will stop execution early and inform you as to what you're missing.

Providing you've done everything correctly, you should now be able to create your infrastructure using

node useGantree.js

If you're experiencing any unhandled errors - even after following this tutorial word-for-word - please don't hesitate to submit an issue on Github. The more details you give us, the easier it is for us to help you out and potentially fix bugs for everyone.