Introduction

deploy-lang is a programming language to manage state across time and across multiple machines/environments. deploy-lang is a polyglot programming language where different sections are written in different syntax optimized specifically for the type of work to be done. deploy-lang separates the concepts of data vs actions, allow data to be written declaratively, and actions to be written imperatively.

Hello World

Before we get into technical details about deploy-lang, let's look at a simple hello world example to get started.

Create a file called hello_world.dpl anywhere you'd like, and copy paste the following into your file:

state
   file mystate.json

Now let's run our program using the deploy-lang cli. Simply run:

deploy-lang ./hello_world.dpl

After running this, you should see that a file was created in your current directory called mystate.json.

If you run cat mystate.json you can print the contents of this file, which should look something like this:

{
  "dpl_metadata": null,
  "resources": {}
}

As you may have guessed, the mystate.json file contains the entire state of your application. An application's state is composed of resources, which currently is an empty set! We'll learn more about state and resources in a later chapter, but let's wrap up our hello world example by actually creating a resource.

Edit your hello_world.dpl file and add the following after your state section:

template echo
  create
    echo "hello world!"

resource echo(my_first_resource)
  {}

Your full hello_world.dpl file should now look like this:

state
  file mystate.json

template echo
  create
    echo "hello world!"

resource echo(my_first_resource)
  {}

We added 2 new sections to the hello_world.dpl file: a template section that is named echo, and a resource section that calls the template echo and is named my_first_resource.

Now run the deploy-lang cli again:

deploy-lang ./hello_world.dpl

You should see some CLI output that contains

resource 'my_first_resource' OK

Now examine the mystate.json file again and you should see it contains the following:

{
  "dpl_metadata": null,
  "resources": {
    "my_first_resource": {
      "resource_name": "my_first_resource",
      "template_name": "echo",
      "last_input": {},
      "output": "hello world!",
      "depends_on": []
    }
  }
}

Here we can see that our state file now has 1 resource: the resource "my_first_resource" that we wrote in the hello_world.dpl file. This resource also has some extra information such as what template it called, its input and its output.

We could wrap up the hello world example here, but let's drive home the point of what deploy-lang is all about: deploy-lang is about managing resources over time. Run the deploy-lang command again:

deploy-lang ./hello_world.dpl

What happened? nothing! You should not have seen the output resource 'my_first_resource' OK. Why not? because nothing changed from the last time you ran deploy-lang. Your resource did not need to be updated because the inputs did not change. Remember in the mystate.json file we saw that it contained "last_input": {}? That's the part of the state that is compared against your resource's current input (the body of the my_first_resource resource in your hello_world.dpl file).

Edit your hello_world.dpl file and change the resource's body to something else, for example change it to this:

# rest of the .dpl file omitted for brevity

resource echo(my_first_resource)
  { "a": "b" }

Then run the deploy-lang command again:

deploy-lang ./hello_world.dpl

You should see that it errors! It should have printed out an error message that contains something like

resource 'my_first_resource' is to be updated but template 'echo' does not define any update commands

You updated your resource, and ran the deploy-lang cli again. deploy-lang saw that your resource's current input differs from its last input, and therefore it needs to be updated. but the template that it calls does not support updates! We can see from the template that it only has a subsection called create which will run echo "hello world"!.

In later chapters we'll learn more about templates, resource lifecycles and more.

Concepts

A deploy-lang file (.dpl file) contains several root level concepts to be aware of that will help form a mental model of how deploy-lang works.

Comments

A .dpl file uses the # character for comments. Multiline comments are not supported. The # character can appear above/around sections, or at the end of a line. Certain sections such as resource sections even support comments in its body, for example consider this sample .dpl file:

# comment above a resource
resource some_template(my_resource_name) # comment on the same line
  {
    # you can have comments here!
    "a": {
      # and here!
      "b": "c" # and here!
    }
  }

Sections

A .dpl file is composed of sections, each section potentially written in a different syntax/language. A section starts with a keyword describing the section type. common section types are resource, template, state. Following the section type, on the same line, are optional parameters to the section.

After the section type and optional parameters comes the section body. DPL is indentation based, so the body must have at least 1 character of whitespace (either a tab or a space). The section body contains all lines with at least 1 whitespace character until an empty line is found (or the end of the document), in other words a section must end with \n\n. Let's look at a full example of a resource section:

#                 /---  parameters ---\
#                |                     |
# section type   |                     |
#   |           /                      |
#   |          /                       |
#   |         /                        |
#   |        /                         |
#   |       /                          |
#  /       /                           |
# |       /                            |
# v      v                             v
resource some_template(my_resource_name)
  {                                      #  body starts here
    "hello": "world"                     #  body
  }                                      #  body ends here

The section type is resource, the parameters are some_template(my_resource_name) and the body includes three lines of json:

  {
    "hello": "world"
  }

File

deploy-lang is written in files with extension .dpl, from here forward we may refer to deploy-lang, .dpl files, and DPL files interchangeably. Above we showed an example of a single section in a DPL file, but usually a DPL file will be composed of several different sections, each section potentially having a different syntax, and performing a different task. Let's look at a simple DPL file that has a variety of section types:

state
   file mystate.json

template hello
  create
    echo "hello world!"

resource hello(my_first_resource)
  {}

In this example, we have 3 sections, a state section, a template, and a resource section.

The state section defines where deploy-lang will read and write your state. The state section does not have any parameters. This section's body simply has file mystate.json, which tells deploy-lang that state will be managed simply via a file on disk, and that file is called mystate.json. In a later chapter we will explore state more in-depth and see different types of state that deploy-lang can read/write to/from.
After the state section we have a template section. This section does have a parameter and the parameter is hello. Template sections must have a parameter which is interpreted to be the name of the template. The body of the template simply says "on creation, run an "echo" command to echo "hello world!". Templates can be fairly complex, and in a later chapter we will learn more about templates, but for now just know that we have defined a template called hello that can print out "hello world!"
Finally, we have a resource section, this also must have a parameter, which is interpreted to be the template that the resource "calls" and in parentheses is the name of the resource. The resource section must have a body, which is JSON, and in this case it's just an empty JSON object.

Keyboard shortcuts

deploy-lang