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

​

Passing Orbital application configuration

There are several configuration settings referenced throughout these docs, which can be used to fine-tune how Orbital behaves.

All config settings can be passed in a variety of ways:

​

Docker

In a docker / docker compose file, pass variables using the OPTIONS environment variable:

services:
   orbital:
      image: orbitalhq/orbital:latest
      environment:
         OPTIONS: >-
            --vyne.db.username=orbital
            --vyne.db.password=changeme
            --vyne.db.host=postgres

​

Setting as Environment variables

Alternatively, any setting can be defined as an environment variable.

Environment variables follow a different convention, so to convert, apply the following:

• Use uppercase
• Remove dashes
• Replace dots with underscores

eg:

​

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.

Orbital 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"
      }
   ]
}

​

Configuring where Orbital finds other Orbital services

There are some services that Orbital will try to contact over HTTP(s), such as Prometheus for monitoring, or Nebula for stub services.

You can override the default URLs used for Orbital-specific services by writing a services.conf file.

By default, Orbital expects to read this from config/services.conf, but you can configure this path by passing a path to --vyne.services.config-file on startup.

services {
    orbital-prometheus {
        url="http://localhost:9090"
    }
   nebula {
      url="http://localhost:8099"
   }
}

​

Orbital Deployments Behind AWS / Azure Load Balancers

AWS / Azure load balancers have idle timeout setting which refers to the duration of time that the load balancer allows an idle connection to remain open. An idle connection refers to a connection where no data is being transmitted between client and server. Between Orbital Server and UI, there are various websocket connections. For instance, Orbital server transmits endpoint statuses to UI over a websocket. To prevent these connections marked as idle connections and terminated by AWS / Azure ALB, you can enable a heartbeating mechanism by setting the following configuration variables: