Skip to main content
Version: Next

Get Started Now

You can get up and started with opscotch in no time at all.

The goal of this document is to show a minimal proof of running a minimal application in an Opscotch runtime.

First time here?

You can follow along with this demonstration with your own opscotch runtime, however

If you're feeling a bit overwhelmed, simply read this page to the end without running the runtime yourself.

When you see how easy it is, follow along with your own opscotch runtime.

Prerequisites

Before you start you'll need a few prerequisites:

  • We'll be working in your operating system's terminal, so you need to know what that is and how to use it

  • You'll need a copy of the opscotch development runtime executable that is compatible with the operating system that you are using. See the downloads page

  • Create a directory somewhere to work in, put all the files there, including the opscotch executable

  • Make sure you've read the Basic Concepts, specifically the "moving parts"

  • The development runtime includes a free development license, so you do not need a separate license for this getting started example

  • If you want to do this with the production runtime instead, you will need a production license

A note for Windows users
  • any text file that you edit needs to be saved as UTF-8 with LF line feeds
  • any file paths in text files needs to either use / instead of \ or escape \ like \\
A note for all users
  • When using paths in text files, where possible use the full path to avoid errors.

File setup​

In this example you'll be working with files. For your reference we'll outline the file structure now for you to refer back to:

working directory
|\_ opscotch-runtime
 \_ configs                        (configs for deploying to the runtime)
    \_ bootstrap.json              (bootstrap file)
    \_ helloworld.config.json      (workflow configuration file)
    \_ helloworld.oapp             (packaged workflow configuration file)

Hello World Example​

Let's get things started with the classic computing test: the "hello world". Let's create the simplest configuration that will print "hello world".

In the Basic Concepts we talk about the bootstrap - this is the first configuration that the runtime loads.

The bootstrap​

Create a file in your configs directory called bootstrap.json with the following content:

[
    {
        "deploymentId" : "hello-world",
        "remoteConfiguration" : "configs/helloworld.config.json"
    }
]

Note: the remoteConfiguration property includes the configs directory - this file is specified relative to the runtime, not the bootstrap file.

In the first terminal start the opscotch development runtime (use the binary that matches your distribution) from the working directory and reference the bootstrap that we just created:

If your runtime binary has a slightly different filename in your environment, substitute that filename in the commands below.

opscotch-runtime --accept-legal=yes configs/bootstrap.json

The runtime should start and you should get a message along the lines of (amongst others)

Listening for changes to: configs/helloworld.config.json
Configuration Watcher Loaded
Bootstrap configuration loaded
Agent initialisation complete
Activating Workflows
File watch created (using directory watch) for: configs/helloworld.config.json
Directory watch created on: configs

When you have got this far: Yay! The runtime is happy enough to run.

Leave it running, but keep the terminal visible so you can see any activity.

The Workflow Configuration​

The next step is to create the workflow configuration:

In the Basic Concepts we discussed the "workflow configuration".

Create a file in your configs directory called helloworld.config.json and copy this into it:

{
    "workflows" : [
        {
            "name" : "hello world",
            "steps" : [
                {
                    "stepId" : "hello",
                    "resultsProcessor" : {
                        "script" : "console.log('hello world');"
                    },
                    "trigger" : {
                        "runOnce" : true
                    }
                }
            ]
        }
    ]
}

And there it is. Because the runtime is already running, it should automatically pick up the new file.

On the runtime terminal you should see something like:

File change detected for deploymentId: hello-world
New configuration loaded for deploymentId:hello-world
Starting: hello-world-...-hello/...
hello world

Try changing the workflow configuration so it logs hello world from opscotch instead. Save the file and watch the runtime pick up the change automatically and print the new output.

Add the Packager​

Now that the simple raw-configuration flow is working, let's add the packager.

We'll use the evergreen (always up-to-date) packager app here:

https://github.com/opscotch/opscotch-apps/releases/download/opscotch-packager-latest/opscotch-packager.oapp

Update your configs/bootstrap.json so it includes both the hello world deployment and the packager deployment:

Edit the same configs/bootstrap.json file in place. Do not create a second bootstrap file.

[
    {
        "deploymentId" : "hello-world",
        "remoteConfiguration" : "configs/helloworld.config.json"
    },
    {
        "deploymentId": "opscotch-packager",
        "remoteConfiguration": "https://github.com/opscotch/opscotch-apps/releases/download/opscotch-packager-latest/opscotch-packager.oapp",
        "persistenceRoot": "persistence",
        "allowHttpServerAccess": [
            {
                "id": "api",
                "port": 22222
            }
        ],
        "packaging": {
            "packageId": "opscotch-packager",
            "packagerIdentities": [
                "opscotch-packager-identiy"
            ],
            "requiredSigners": [
                {
                    "id": "opscotch-app",
                    "description": "Official opscotch app"
                },
                {
                    "id": "opscotch-packager-app",
                    "description": "Official opscotch Packager"
                },
                {
                    "id": "opscotch-packager-1.x",
                    "description": "Opscotch Packager v2 version 1.x lock"
                }
            ]
        },
        "keys": [
            {
                "id": "opscotch-packager-identiy",
                "type": "public",
                "purpose": "authenticated",
                "keyHex": "D1F8F5CD6424A638A938903EBEA7C140A678873417E5642A3993D2C1BE74A01E"
            },
            {
                "id": "opscotch-app",
                "type": "public",
                "purpose": "sign",
                "keyHex": "8C9AED01FF5E6695E4464E754697F22D653A9FB35E1233627D81D91F89CF2874"
            },
            {
                "id": "opscotch-packager-app",
                "type": "public",
                "purpose": "sign",
                "keyHex": "6D9841078C83239B1CF148BF92A533A4C8BA4901DA0AD1ADDE2FE2D23BA3F156"
            },
            {
                "id": "opscotch-packager-1.x",
                "type": "public",
                "purpose": "sign",
                "keyHex": "5912C087D6C958A84433F666784CE228B17EF34E39E5D9C7FD2BBA5927A760F9"
            }
        ]
    }
]

Because the bootstrap changed, restart the runtime.

This packager bootstrap includes the signing and authentication keys from the published packager release. They could be omitted, but keeping them here is the better practice because the runtime can then verify the packager app instead of loading it without those checks.

Use the same command as before:

opscotch-runtime --accept-legal=yes configs/bootstrap.json

This time the logs should also show that the HTTP server is running on port 22222.

Package the Workflow​

In the other terminal run the packager API:

curl "http://localhost:22222/workflow-package" \
  -v \
  -H "Accept: application/octet-stream" \
  -F 'body={ "packageId": "hello-world" }' \
  -F 'stream=@configs/helloworld.config.json;type=application/octet-stream' \
  --output configs/helloworld.oapp

You should see something like:

< HTTP/1.1 200 OK

This means that it has sucessfully taken the configs/helloworld.config.json we've been working with and compiled it into an opscotch app (configs/helloworld.oapp).

Now edit the existing hello-world entry inside the bootstrap array so it references the packaged file instead of the raw config. Do not replace the whole bootstrap file, because the opscotch-packager entry still needs to stay there. We also need to add the packaging block so that it matches what was passed into the packager:

[
    {
        "deploymentId" : "hello-world",
        "remoteConfiguration" : "configs/helloworld.oapp",
        "packaging": {
            "packageId": "hello-world"
        }
    },
    {
        "deploymentId": "opscotch-packager",
        "remoteConfiguration": "https://github.com/opscotch/opscotch-apps/releases/download/opscotch-packager-latest/opscotch-packager.oapp",
        "persistenceRoot": "persistence",
        "allowHttpServerAccess": [
            {
                "id": "api",
                "port": 22222
            }
        ],
        "packaging": {
            "packageId": "opscotch-packager",
            "packagerIdentities": [
                "opscotch-packager-identiy"
            ],
            "requiredSigners": [
                {
                    "id": "opscotch-app",
                    "description": "Official opscotch app"
                },
                {
                    "id": "opscotch-packager-app",
                    "description": "Official opscotch Packager"
                },
                {
                    "id": "opscotch-packager-1.x",
                    "description": "Opscotch Packager v2 version 1.x lock"
                }
            ]
        },
        "keys": [
            {
                "id": "opscotch-packager-identiy",
                "type": "public",
                "purpose": "authenticated",
                "keyHex": "D1F8F5CD6424A638A938903EBEA7C140A678873417E5642A3993D2C1BE74A01E"
            },
            {
                "id": "opscotch-app",
                "type": "public",
                "purpose": "sign",
                "keyHex": "8C9AED01FF5E6695E4464E754697F22D653A9FB35E1233627D81D91F89CF2874"
            },
            {
                "id": "opscotch-packager-app",
                "type": "public",
                "purpose": "sign",
                "keyHex": "6D9841078C83239B1CF148BF92A533A4C8BA4901DA0AD1ADDE2FE2D23BA3F156"
            },
            {
                "id": "opscotch-packager-1.x",
                "type": "public",
                "purpose": "sign",
                "keyHex": "5912C087D6C958A84433F666784CE228B17EF34E39E5D9C7FD2BBA5927A760F9"
            }
        ]
    }
]

Restart the runtime again.

The same hello world from opscotch log should appear, but this time it is running from the packaged app.

At this point the runtime is loading configs/helloworld.oapp, not configs/helloworld.config.json directly. That means changes to configs/helloworld.config.json will not affect the runtime until you package the file again.

Then edit configs/helloworld.config.json again so it logs hello world from opscotch packaged and package it again with the same curl command.

The runtime should immediately pick up the new packaged file and print the updated output.

Remember to shutdown the opscotch runtime that you started using ctrl-c

Wrapping up​

In this demonstration we've shown how:

  • to create the bootstrap
  • to start the opscotch development runtime
  • to run a workflow directly from a raw configuration file
  • to add and use the packager inside the runtime
  • to package a workflow and run it as a packaged app

Troubleshooting​

  • If port 22222 is already in use, change the allowHttpServerAccess port in the packager bootstrap entry and use the same new port in the curl command.
  • If the runtime cannot download the packager app from GitHub, check that the machine running the runtime has outbound network access to github.com and GitHub release downloads.
  • If the runtime does not pick up your changes, check that your JSON is still valid and that you edited the existing configs/bootstrap.json file rather than creating a second bootstrap file.