Configuring Orbital

Orbital can be configured through a series of config files, passed at runtime.

We designed Orbital this way to encourage scripted deployments, (as opposed to using a config database, which is hard to script).

Orbital uses HOCON format for it’s config files. (HOCON is a superset of JSON, so JSON is also valid.)

​

Configuration basics

There’s several common themes in how Orbital configuration works.

​

Creating reasonable defaults

If you don’t provide a config file, Orbital will create one for you on startup, and populate it with reasonable defaults.

​

Environment variables and sensitive data

Often configuration files need to contain sensitive data (usernames, passwords, etc).

It may not always be desirable to specify sensitive connection information directly in the config file - especially if these are being checked into source control.

Environment variables can be used anywhere in the config file, following the HOCON standards.

For example:

jdbc {
   some-database-connection {
      connectionName = some-database-connection
      # .. other params omitted for bevity ..
      connectionParameters {
         # .. other params omitted for bevity ..
         password = ${postgres_password} # Reads the environment variable "postgres_password"
      }
   }
}

​

Correctly handling substitutions in Urls

In some config files, you’ll need to specify URLs, and will want to use variables. Using a variable inside a url using Hocon can be tricky.

In short, here’s how substitutions need to be defined:

query-server {
   // The Url has specifal characters (:), so needs to be inside of quotes.
   // However, variable substitution doesn't work inside of quotes,
   // so the variable must be outside of quotes.
   url="http://"${MY_VARIABLE}":9305"
}

For more information, see this issue in the Hocon library

​

Configuring the Schema Server

The schema repositories that Orbital is connected to can be configured through a config file.

By default, this file is called schema-server.conf, however that can be modified by passing a command-line argument when starting the schema server:

For example, in a Docker Compose file:

version: "3.3"
services:
  ## Other services omitted
   schema-server:
      image: orbitalhq/schema-server:latest
      environment:
         OPTIONS: >-
            --orbital.repositories.config-file=/var/lib/orbital/schema-server/schema-server.conf

​

Configuring git repositories

In production, it’s common to read (and write) from a git repository, rather than a local file system.

This allows the use of standard git workflows to promote changes to ‘production’.

The schema server will periodically poll a git repository and branch, and pull in any changes as they’re detected

​

Using access tokens

Github and Gitlab support embedding access tokens within the url of the git repository.

Here’s an example:

git {
   checkoutRoot="/some/path"
   repositories=[
      {
         branch=master
         name=my-taxonomy
         uri="https://jimmy:glpat-purple-tortoise@gitlab.com/acme/acme-taxonomy"
      }
   ]
}

​

Example

git {
   # Defines the root folder where git repositories will be checked out to.
   # Each repository gets its own subdirectory under this path
   checkoutRoot="/my/git/root"

   # Defines the frequency that Orbital will poll for updates
   # against the git repository
   pollFrequency=PT30S

   # A collection of repositories to fetch
   repositories=[
      {
           name=my-git-project
           branch=master
           uri="https://github.com/something.git"

           # Optional
           sshAuth={
               privateKeyPath='/my/path/to/key'
               # Optional.
               # You can use environment variables here
               passphrase: CorrectHorseBatteryStaple
           }

           # Defines if Orbital can submit changes to this repository
           # (eg., for edits from the UI)
           isEditable: true | false

           # If Orbital is making changes, providing
           # pullRequestConfig means that changes are submitted
           # via a pull request, rather than comitted directly onto the defined branch
           pullRequestConfig={
              branchPrefix: "schema-updates/"
           }
      }
   ]
}

​

Kitchen Sink config example

file {
   changeDetectionMethod=WATCH
   incrementVersionOnChange=false
   paths=[
      "/path/to/project"
   ]
   pollFrequency=PT5S
   recompilationFrequencyMillis=PT3S
}
git {
   checkoutRoot="/my/git/root"
   pollFrequency=PT30S
   repositories=[
      {
         branch=master
         name=my-git-project
         uri="https://github.com/something.git"
      }
   ]
}