# Configuring Orbital

> Orbital can be configured through a series of config files

Source: https://orbitalhq.com/docs/deploying/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](https://github.com/lightbend/config#examples-of-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](https://github.com/lightbend/config#uses-of-substitutions).

For example:

```HOCON
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:

```hocon
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](https://github.com/lightbend/config/issues/633) in the Hocon library

### Environment variables in annotations
Sometimes it's desirable to variable things defined in annotations by envirnoment.

For example, you may wish to modify the URL of an HTTP service, the name of a database table, or a the name of a Kafka topic
that you subscribe to, based on environment.

For example:

```taxi
service QuotesService {
   @KafkaOperation(topic = "${STOCK_PRICE_TOPIC}")
   stream quotes : Stream<StockPrice>
}
```


**Note**
Environment variables in annotations is **not** a feature of the standard Taxi compiler - this capability is provided by Orbital, so will not work when using the Taxi CLI etc.

Environment variables here can be resolved from (in order of precedence):
 - An [env.conf config file](/docs/deploying/managing-secrets#using-env-conf-for-sensitive-data)
 - System environment variables

## Environment specific configuration 

_Available since 0.37.0_

Orbital supports loading environment-specific variations of configuration files, making it easy to manage different settings across environments (development, staging, production, etc.) without duplicating configuration files.

### How it works

When an environment name is configured, Orbital will automatically load both the base configuration file and its environment-specific variation (if present).

For example, if you configure `--vyne.environment.name=preprod`, Orbital will load:
- `auth.conf` (base configuration)
- `auth.preprod.conf` (environment-specific overrides, if present)

This applies to all configuration files including:
- `auth.conf` / `auth.<environment>.conf`
- `services.conf` / `services.<environment>.conf`
- `env.conf` / `env.<environment>.conf`
- `connections.conf` / `connections.<environment>.conf`
- Pipeline configuration files (`*.conf` / `*.<environment>.conf`)

### Configuration

Set the environment name when starting Orbital:

#### Docker
```yaml
services:
   orbital:
      image: orbitalhq/orbital:latest
      environment:
         OPTIONS: --vyne.environment.name=preprod
```

#### Environment variable
```bash
export VYNE_ENVIRONMENT_NAME=preprod
```

### Behavior

- **Both files are loaded**: If both the base file and environment-specific file exist, both are loaded and merged
- **Graceful fallback**: If the environment-specific file doesn't exist, only the base file is loaded (no error)

When running with `--vyne.environment.name=production`, both files are loaded, allowing the production-specific settings to override or extend the base configuration.

## 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:

```yaml
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:

| Application property         | Environment variable         |
|------------------------------|------------------------------|
| `vyne.db.username`           | `VYNE_DB_USERNAME`           |
| `vyne.workspace.config-file` | `VYNE_WORKSPACE_CONFIGFILE` |

## 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:

```hocon
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 test environments.

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.

**Note**
`services.conf` supports environment-specific variations. For example, you can create `services.production.conf` for production-specific service URLs. See [Environment-specific configuration files](#environment-specific-config) for details.


```hocon
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:

 Application property                  | Description                       | Value 
|--------------------------------------|-----------------------------------|----------------------------------------------------|
| `vyne.ws.enablePing`                 | Enables Websocket hearbeats       | true = enable heatbeats, false = disable heartbeats|
| `vyne.ws.pingIntervalInMilliSeconds` | Heatbeat interval in milliseconds | Any Long value                                     |