Deploying Orbital

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.

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:


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

      image: orbitalhq/orbital:latest
         OPTIONS: >-

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
  • Replace dashes and dots with underscores


Application propertyEnvironment variable

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 {
Production deployments
Managing secrets