Skip to main content
Version: 3.0.0

Get Started Now

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

First time here?

You can following along with this demonstration with your own opscotch agent, however

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

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

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 agent and configuration packager executables 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 executables

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

  • You'll needs an opscotch (trial) license key

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 (please do create the configs sub-directory, we'll be adding other ones later so adding it now will make sense later):

working directory
|\_ opscotch-agent
|\_ opscotch-packager
 \_ configs                        (configs for deploying to the agent)
    \_ test.bootstrap.json         (bootstrap file)
    \_ test.config.json            (workflow configuration file)
    \_ test.config                 (packaged workflow configuration file)
    \_ test.package.config.json    (packaging configuration file)
    \_ license.txt                 (your license file)
    \_ agent.public.key            (agent public key file)

"hello world"​

Let's get things started with the classic computing test: the "hello world". Lets 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 agent loads.

ONLY USE THE PROVIDED KEYS FOR THIS EXAMPLE

The opscotch system uses public/private keys to encrypt and make sure the agent doesn't run something you didn't write.

In this example we've provided a public/private key set: ONLY USE THE PROVIDED KEYS FOR THIS EXAMPLE

Do not use these keys for your agents other than for this demonstration

The bootstrap​

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

[
    {
        "remoteConfiguration" : "configs/test.config",
        "deploymentId" : "opscotch-examples",
        "agentPrivateKey" : "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCk1JSUV2UUlCQURBTkJna3Foa2lHOXcwQkFRRUZBQVNDQktjd2dnU2pBZ0VBQW9JQkFRRGF0VGRhcC81TVQ5bzkKemYyUXZ1akZQeTUrWmZsYi9UZzZBRkROSERCcHpQMldSZU5TNkJkL3JqaEE4NnpiTWJlN2pxcFZJbFp0eFQ0dwpKYzNMM0c0UmxOVEM5VVczMmxyNjBJYWRFOU1xcTZYdENicWVGQlVxV0tFb1RjaWQyVUlFSDRpMG9sbkF2ditICnRKeUJrZ3NVV0w5cmN4dFloODZmK3dqVEFoSmNCS1RMcFZkakFoMHJkS0RuSmxXSHJ4NkswNVlZc2RLR1pyTHcKSTJCekpSZytlREp3SEo5MExUUEhVTFB0Ni9QN1ppUDBObHc5ZnYzYjlncVJiaW1ZMzFUQ2xxZ2k2eXR1K2dhRgpMbjNzdW1nUjBZVUR1d0RhaGlYZVlPZ0JtdjBjS3RuWlBMZitwblpubThRR3ZWcVF2T2JXSlpzUmYreXc1Nk91CkRMYUJhYnFqQWdNQkFBRUNnZ0VBQ3FpdVMvTElCL3dVVE5MUE90Q3pFM25pMERJMEZ2R2VYZVZLQ3RVRzN3RW8Ka3J4Uk9lY3B6Z1UxcEtTN2xlczBZeVd1MDN0YTd2cWY3MFRJWk5rWFhDLyt0b214bmlZOExPRWd6bUw2OWFkcgo3TU4rbnRtbnRtcWZZQkY2WjRjQkdxWld5VWJvVE9hQ0dhRUp4NTdRZjJ0YjJPYkJQRzFSK3FZSFpoRkJ4ODR6CkVMTllhSkZLdFV2cTl0L1RpbFI2VExYZU8yOGhFejJSUnRVanRLc1JKWlRtdkRkNVZtRkNJZnV3UjRPZHJIUjMKTndSRnBwbmdMc1Y1ZWxjN25TYXBuaG1pZnVscEFnZFJjclFjaGpEYjlpa2s5Uk9nWmprOHozNkFWempQT1E1NgpoelVmTWcvMk54eFJNOHpBdC9xdExmdFN0NlpOTHJCVjFENHVDbXBWY1FLQmdRRHdkRWszRnF0dWptNFhxQ2o3Cm55Q0pqN3VBQjFGR0ZlemU1cFM1SVIyU3o0Ri9FQW9PTTlUbjA3cWNpamY2c0RTVGF5WEh2V0xlVTdENkljZSsKb3AycXZUTXpHMTRxZHpMTkk2SVVNbERZWVJVYTVtVHFzY1hCeCtxMTUxOE4zUVhpQ1IvQ1EwbGR4SFVRTXkzcgo3NXlKTXd1aEtrTVdHZGVSVXpVN0N5SFpoUUtCZ1FEbzJRS1c3WGIxNW1TY2xEVElMc1JrZVk3TEdtZTRweFk5CmU2aHJPUjd3bjE3ZTR5NSsxQmdpcDU0KzR5WitWbWRLcjVQNUdXVW9UQVkwMXRPZ1Q2NmJYMkNHSTBwVFB6OEMKdDRGQS9OT0IrNnNETHhVMDh1dHR6clBEclhWSldLZjNoSHEwRXZTTzJtbUZ6NDV0eE93RDBPZzZHeGZuQll4cwpaYjNQdTRBb0J3S0JnUURuSmxLUHc1b3ZZSHBUQVpQTU42K1dyZmFJWUFCd1NIbDUyZDJVamxJWXBLUVBHc01mCjNoSElmbENCVlpuMHd0ajM4bVBTUEt4RG45NmN4a1ozYTJuNERZT2ZtS3FRVmlBZTlpZEVGUTZFdytiL0FnWjMKVzBnSlBmN1N1VVkyVklmb1ArOG8xM2c2ekxYZ1NlTFdVWFNBcS9KOUR0eUk3WFMrUG1nSWgyNFY1UUtCZ0VXYQpDTUlndlh5SG4rK0dCYmtJOGIrdTdsWWIwSUZMd01Ra0lKWGNmemtpQ25QSnFPNVVhOXFBRERkMEl0K0U2RjlVCjJJQ1BiTU44NWlZSlNUMFVWSGN4TFdNclRWNVErMzdPWjU2TGRKWFlLcWhLL0tYVkx6YWxvT3FQQVE0cHFCdSsKeUFibjI1NlAveGIya2ZhUjlKSzNjWk5jNGVvMnFHRUdrSlIxMGJzbEFvR0FPNHNwekVaTllUQmhIVXZmNUVpRgpFNHM3amVZNE1nSjcrRUhIZm9jTEFPd3QxcmR1V21LQTNTSDhoOWk4bmhUaEhuTGVKc1c3dld6Qk1NQnAvWWFHCmxMUVFtNk8xNytKbVpRakM2OFBiditpcUlOTzlzcm5VUEhkMEU2WEcxUzZwUTVZVExzQXJscmtBZzBScGIzTDkKVDBYWW03MFprYy81WGZuOVNFd0dEV0k9Ci0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0K"
    }
]

Note: the remoteConfiguration property includes the configs directory - this file (which we'll create soon) is specified relative to the agent, not the bootstrap file.

We're going to be working on two things at once, so it is best to have 2 terminal windows open.

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

opscotch-agent configs/test.bootstrap.json

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

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

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

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

Keys​

The opscotch system uses public/private keys to encrypt and make sure the agent doesn't run something you didn't write. The private key for this demonstration only is in the bootstrap above, lets create the public key file in your configs directory for this demonstration only: configs/agent.public.key, and paste the following:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2rU3Wqf+TE/aPc39kL7o
xT8ufmX5W/04OgBQzRwwacz9lkXjUugXf644QPOs2zG3u46qVSJWbcU+MCXNy9xu
EZTUwvVFt9pa+tCGnRPTKqul7Qm6nhQVKlihKE3IndlCBB+ItKJZwL7/h7ScgZIL
FFi/a3MbWIfOn/sI0wISXASky6VXYwIdK3Sg5yZVh68eitOWGLHShmay8CNgcyUY
PngycByfdC0zx1Cz7evz+2Yj9DZcPX792/YKkW4pmN9UwpaoIusrbvoGhS597Lpo
EdGFA7sA2oYl3mDoAZr9HCrZ2Ty3/qZ2Z5vEBr1akLzm1iWbEX/ssOejrgy2gWm6
owIDAQAB
-----END PUBLIC KEY-----
Notes on keys

Please see the details on how to use keys

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 test.config.json and copy this into it:

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

Thats it for the configuration - before we can use it, we need to run the packager to prepare it for the agent.

The packager​

The packager needs to know some more info and we add that to a packager configuration.

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

{
    "license" : "configs/license.txt",
    "agentPublicKey" : "configs/agent.public.key",
    "resourceDirs" : ["."],
    "configPath" : "configs/test.config.json"
}

Note: You'll need to replace the contents of configs/license.txt with your supplied license, ie paste in the contents of your license.

Lets package this config (it will write to the file configs/test.config) and see what happens, make sure you have both your terminals visible... you should be able to see the terminal with the agent running.

In the other terminal run the packager:

cat configs/test.config.json | opscotch-packager workflow configs/test.package.config.json > configs/test.config

You should see something like:

Success: version: 7e6c98a7

And on the agent terminal you should see something like:

File change detected for deploymentId: opscotch-examples
License accepted: ...
New configuration loaded configversion:14963e2c for deploymentId:opscotch-examples from fileversion:7e6c98a7
File watch created (using directory watch) for: configs/test.config
Directory watch created on: configs
Starting: opscotch-examples-14963e2c-hello/2111400670
hello world

And there it is! "hello world".

Take a look at the test.config file - you'll see that its encrypted, and will only be decrypted by an agent with the matching private key.

Note: If your packaging is not successful you will likely see an error message from the agent like Can not load zero length file. Check packaging. This is just letting you know that there was something wrong with the packaging. Try find and fix the problem.

Wrapping up​

In this demonstration we've shown how:

  • to create the bootstrap
  • to create a workflow configuration
  • to use the public/private keys to secure the configurations
  • to use the packager and how the agent automatically updates the workflow configuration when the packager changes it