Config

An application's configuration settings.

Use configuration to add customized behavior to your app

Quick Start

In your application's working directory, there should be a subfolder called Config/ that will be searched for configuration files. The first thing we'll add is app.json, here's how the directory should look

Text

./
├── Config/
│   ├── app.json

There are a few keys that Vapor will use automatically. Right now, let's customize our application's host and port. Here's how our app.json file should look now:

JSON

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

Now when our application loads, it'll automatically run on port 8080.

Custom Keys

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

JSON

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

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

Swift

let customValue = app.config["app", "custom-key"].string

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 app.json file we mentioned earlier, there is also a keys.json that looks like this:

JSON

{
  "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:

Swift

let name = app.config["keys", "test-names", 0].string

Or our mongo url:

Swift

let mongoUrl = app.config["keys", "mongo", "url"].string

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 app file, but more complex options are also available.

1. --key=value

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

Text

--mongo-password=$MONGO_PASSWORD

would be accessible within your application by using the following:

Swift

let mongoPassword = app.config["app", "mongo-password"].string

2. --config:file-name.key=custom-value

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

Text

--config:keys.analytics=124ZH61F

would be accessible within your application by using the following:

Swift

let analyticsKey = app.config["keys", "analytics"].string

Advanced Configuration

Having the default app.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 folder structure to our Config/ directory. Here's an example of a folder structure that's setup for production and development environments.

Text

WorkingDirectory/
├── Config/
│   ├── app.json
│   ├── production/
│   │   └── app.json
│   ├── development/
│   │   └── app.json
│   └── secrets/
│       └── app.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.

Text

vapor run --env=production

Priority

Config files will be accessed in the following priority.

1. CLI (see below)
2. Config/secrets/
3. Config/name-of-environment/
4. Config/

What this means is that if a user calls app.config["app", "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. (click names to see)

app.json

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

production/app.json

{
  "host": "127.0.0.!"
  "port": 80
}

secrets/app.json

{
  "mongo-user": "secret-user",
  "mongo-pass": "secret-pass"
}

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

Swift

// will load 0.0.0.0 or 127.0.0.1 based on above config
let host = app.config["app", "host"].string
// will load 9000, or 80 based on above config
let port = app.config["app", "port"].int

Config will load the appropriate value given the current environment. Our secrets file is accessed the same way

Swift

let user = app.config["app", "mongo-user"].string
let pass = app.config["app", "mongo-pass"].string

If the secrets file is not present, these values will be nil.