✎ Edit on GitHub

Config

An application's configuration settings. Cloud applications generally require complex configurations that can adjust based on their environment. Vapor intends to provide a flexible configuration interaction that can be customized for a given user.

QuickStart

For Vapor applications, configuration files are expected to be nested under a top level folder named Config. Here's an example of a basic config featuring a single servers configuration.

./
├── Config/
│   ├── servers.json

And an example of how this might look:

{
  "http": {
    "host": "0.0.0.0",
    "port": 8080
  }
}

What that's saying, is that our application should start a single server named 'http' serving port 8080 on host 0.0.0.0. This represents the following url: http://localhost:8080.

Custom Keys

Let's add a custom key to the servers.json file:

{
  "http": {
    "host": "0.0.0.0",
    "port": 8080,
    "custom-key": "custom value"
  }
}

This can be accessed from your application's config using the following.

let customValue = drop.config["servers", "http", "custom-key"]?.string ?? "default"

That's it, feel free to add and utilize keys as necessary to make your application configuration easier.

Config Syntax

You can access your config directory with the following syntax. app.config[<#file-name#>, <#path#>, <#to#>, <#file#>]. For example, let's hypothesize that in addition to the servers.json file we mentioned earlier, there is also a keys.json that looks like this:

{
  "test-names": [
    "joe",
    "jane",
    "sara"
  ],
  "mongo": {
    "url" : "www.customMongoUrl.com"
  }
}

We can access this file by making sure the first argument in our subscript is keys. To get the first name in our list:

let name = drop.config["keys", "test-names", 0]?.string ?? "default"

Or our mongo url:

let mongoUrl = drop.config["keys", "mongo", "url"]?.string ?? "default"

Advanced Configurations

Having the default servers.json is great, but what about more complex scenarios. For example, what if we want a different host in production and in development? These complex scenarios can be achieved by adding additional folders to our Config/ directory. Here's an example of a folder structure that's setup for production and development environments.

WorkingDirectory/
├── Config/
│   ├── servers.json
│   ├── production/
│   │   └── servers.json
│   ├── development/
│   │   └── servers.json
│   └── secrets/
│       └── servers.json

You can specify the environment through the command line by using --env=. Custom environments are also available, a few are provided by default: production, development, and testing.

vapor run --env=production

PRIORITY

Config files will be accessed in the following priority.

CLI (see below)
Config/secrets/
Config/name-of-environment/
Config/

What this means is that if a user calls app.config["servers", "host"], the key will be searched in the CLI first, then the secrets/ directory, then the top level default configs.

secrets/ directory should very likely be added to the gitignore.

EXAMPLE

Let's start with the following JSON files.

`servers.json`

{
  "http": {
    "host": "0.0.0.0",
    "port": 9000
  }
}

`production/servers.json`

{
  "http": {
    "host": "127.0.0.1",
    "port": "$PORT"
  }
}

The "$NAME" syntax is available for all values to access environment variables.

Please notice that servers.json, and production/servers.json both declare the same keys: host, and port. In our application, we'll call:

// will load 0.0.0.0 or 127.0.0.1 based on above config
let host = drop.config["servers", "http", "host"]?.string ?? "0.0.0.0"
// will load 9000, or environment variable port.
let port = drop.config["servers", "http", "port"]?.int ?? 9000

COMMAND LINE

In addition to json files nested within the Config/ directory, we can also use the command line to pass arguments into our config. By default, these values will be set as the "cli" file, but more complex options are also available.

1. `--KEY=VALUE`

Arguments set through the command line can be accessed through config's cli file. For example, the following CLI command:

--mongo-password=$MONGO_PASSWORD

would be accessible within your application by using the following:

let mongoPassword = drop.config["cli", "mongo-password"]?.string

2. `--CONFIG:FILE-NAME.KEY=CUSTOM-VALUE`

If you want command line arguments set to a file besides "cli", you can use this more advanced specification. For example, the following CLI command:

--config:keys.analytics=124ZH61F