{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Config","type":"basic","slug":"config","excerpt":"An application's configuration settings.","body":"Use configuration to add customized behavior to your app\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Quick Start\"\n}\n[/block]\nIn 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\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"./\\n├── Config/\\n│   ├── app.json\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nThere 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"host\\\": \\\"0.0.0.0\\\",\\n  \\\"port\\\": 8080\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nNow when our application loads, it'll automatically run on port 8080. \n\n## Custom Keys\n\nLet's add a custom key to the `app.json` file.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"host\\\": \\\"0.0.0.0\\\",\\n  \\\"port\\\": 8080,\\n  \\\"custom-key\\\": \\\"custom value\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThis can be accessed from your application's config using the following.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let customValue = app.config[\\\"app\\\", \\\"custom-key\\\"].string\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nThat's it, feel free to add and utilize keys as necessary to make your application configuration easier.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Config Syntax\"\n}\n[/block]\nYou 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"test-names\\\": [\\n    \\\"joe\\\",\\n    \\\"jane\\\",\\n    \\\"sara\\\"\\n   ]\\n  \\\"mongo\\\": {\\n  \\t\\\"url\\\" : \\\"www.customMongoUrl.com\\\"\\n\\t}\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nWe can access this file by making sure the first argument in our subscript is `keys`. To get the first name in our list:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let name = app.config[\\\"keys\\\", \\\"test-names\\\", 0].string\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nOr our mongo url:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let mongoUrl = app.config[\\\"keys\\\", \\\"mongo\\\", \\\"url\\\"].string\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Command Line\"\n}\n[/block]\nIn 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.\n\n## 1. --key=value\n\nArguments set through the command line can be accessed through config's app file. For example, the following CLI command:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"--mongo-password=$MONGO_PASSWORD\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nwould be accessible within your application by using the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let mongoPassword = app.config[\\\"app\\\", \\\"mongo-password\\\"].string\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n## 2. --config:file-name.key=custom-value\n\nIf 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"--config:keys.analytics=124ZH61F\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nwould be accessible within your application by using the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let analyticsKey = app.config[\\\"keys\\\", \\\"analytics\\\"].string\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Advanced Configuration\"\n}\n[/block]\nHaving 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"WorkingDirectory/\\n├── Config/\\n│   ├── app.json\\n│   ├── production/\\n│   │   └── app.json\\n│   ├── development/\\n│   │   └── app.json\\n│   └── secrets/\\n│       └── app.json\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n> 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`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"vapor run --env=production\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n## Priority\n\nConfig files will be accessed in the following priority.\n\n1. CLI (see below)\n2. Config/secrets/\n3. Config/name-of-environment/\n4. Config/\n\nWhat 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.\n\n> `secrets/` directory should very likely be added to the gitignore.\n\n## Example\n\nLet's start with the following JSON files. (click names to see)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"host\\\": \\\"0.0.0.0\\\"\\n  \\\"port\\\": 9000\\n}\",\n      \"language\": \"json\",\n      \"name\": \"app.json\"\n    },\n    {\n      \"code\": \"{\\n  \\\"host\\\": \\\"127.0.0.!\\\"\\n  \\\"port\\\": 80\\n}\",\n      \"language\": \"json\",\n      \"name\": \"production/app.json\"\n    },\n    {\n      \"code\": \"{\\n  \\\"mongo-user\\\": \\\"secret-user\\\",\\n  \\\"mongo-pass\\\": \\\"secret-pass\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"secrets/app.json\"\n    }\n  ]\n}\n[/block]\nPlease notice that `app.json`, and `production/app.json` both declare the same keys. `host`, and `port`. In our application, we'll call:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// will load 0.0.0.0 or 127.0.0.1 based on above config\\nlet host = app.config[\\\"app\\\", \\\"host\\\"].string\\n// will load 9000, or 80 based on above config\\nlet port = app.config[\\\"app\\\", \\\"port\\\"].int\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nConfig will load the appropriate value given the current environment. Our secrets file is accessed the same way\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"let user = app.config[\\\"app\\\", \\\"mongo-user\\\"].string\\nlet pass = app.config[\\\"app\\\", \\\"mongo-pass\\\"].string\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nIf the secrets file is not present, these values will be `nil`.","updates":[],"order":9,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5768701b72cd4c0e000fad26","githubsync":"","parentDoc":null,"version":{"version":"0.12","version_clean":"0.12.0","codename":"Client Clyde","is_stable":false,"is_beta":true,"is_hidden":false,"is_deprecated":true,"categories":["5768701b72cd4c0e000fad19","5768701b72cd4c0e000fad1a","5768701b72cd4c0e000fad1b","5768701b72cd4c0e000fad1c"],"_id":"5768701b72cd4c0e000fad18","releaseDate":"2016-06-20T22:37:15.641Z","__v":1,"createdAt":"2016-06-20T22:37:15.641Z","project":"57086fe855a4690e005de407"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Guide","slug":"getting-started","order":1,"from_sync":false,"reference":false,"_id":"5768701b72cd4c0e000fad1a","createdAt":"2016-04-09T04:31:52.489Z","__v":0,"version":"5768701b72cd4c0e000fad18","project":"57086fe855a4690e005de407"},"__v":0,"createdAt":"2016-05-26T22:38:19.979Z","project":"57086fe855a4690e005de407","user":"570997b0ade45d0e00c1acdb"}

Config

An application's configuration settings.

Use configuration to add customized behavior to your app [block:api-header] { "type": "basic", "title": "Quick Start" } [/block] 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 [block:code] { "codes": [ { "code": "./\n├── Config/\n│   ├── app.json", "language": "text" } ] } [/block] 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: [block:code] { "codes": [ { "code": "{\n \"host\": \"0.0.0.0\",\n \"port\": 8080\n}", "language": "json" } ] } [/block] 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. [block:code] { "codes": [ { "code": "{\n \"host\": \"0.0.0.0\",\n \"port\": 8080,\n \"custom-key\": \"custom value\"\n}", "language": "json" } ] } [/block] This can be accessed from your application's config using the following. [block:code] { "codes": [ { "code": "let customValue = app.config[\"app\", \"custom-key\"].string", "language": "swift" } ] } [/block] That's it, feel free to add and utilize keys as necessary to make your application configuration easier. [block:api-header] { "type": "basic", "title": "Config Syntax" } [/block] 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: [block:code] { "codes": [ { "code": "{\n \"test-names\": [\n \"joe\",\n \"jane\",\n \"sara\"\n ]\n \"mongo\": {\n \t\"url\" : \"www.customMongoUrl.com\"\n\t}\n}", "language": "json" } ] } [/block] We can access this file by making sure the first argument in our subscript is `keys`. To get the first name in our list: [block:code] { "codes": [ { "code": "let name = app.config[\"keys\", \"test-names\", 0].string", "language": "swift" } ] } [/block] Or our mongo url: [block:code] { "codes": [ { "code": "let mongoUrl = app.config[\"keys\", \"mongo\", \"url\"].string", "language": "swift" } ] } [/block] [block:api-header] { "type": "basic", "title": "Command Line" } [/block] 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: [block:code] { "codes": [ { "code": "--mongo-password=$MONGO_PASSWORD", "language": "text" } ] } [/block] would be accessible within your application by using the following: [block:code] { "codes": [ { "code": "let mongoPassword = app.config[\"app\", \"mongo-password\"].string", "language": "swift" } ] } [/block] ## 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: [block:code] { "codes": [ { "code": "--config:keys.analytics=124ZH61F", "language": "text" } ] } [/block] would be accessible within your application by using the following: [block:code] { "codes": [ { "code": "let analyticsKey = app.config[\"keys\", \"analytics\"].string", "language": "swift" } ] } [/block] [block:api-header] { "type": "basic", "title": "Advanced Configuration" } [/block] 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. [block:code] { "codes": [ { "code": "WorkingDirectory/\n├── Config/\n│   ├── app.json\n│   ├── production/\n│   │   └── app.json\n│   ├── development/\n│   │   └── app.json\n│   └── secrets/\n│   └── app.json", "language": "text" } ] } [/block] > 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`. [block:code] { "codes": [ { "code": "vapor run --env=production", "language": "text" } ] } [/block] ## 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) [block:code] { "codes": [ { "code": "{\n \"host\": \"0.0.0.0\"\n \"port\": 9000\n}", "language": "json", "name": "app.json" }, { "code": "{\n \"host\": \"127.0.0.!\"\n \"port\": 80\n}", "language": "json", "name": "production/app.json" }, { "code": "{\n \"mongo-user\": \"secret-user\",\n \"mongo-pass\": \"secret-pass\"\n}", "language": "json", "name": "secrets/app.json" } ] } [/block] Please notice that `app.json`, and `production/app.json` both declare the same keys. `host`, and `port`. In our application, we'll call: [block:code] { "codes": [ { "code": "// will load 0.0.0.0 or 127.0.0.1 based on above config\nlet host = app.config[\"app\", \"host\"].string\n// will load 9000, or 80 based on above config\nlet port = app.config[\"app\", \"port\"].int", "language": "swift" } ] } [/block] Config will load the appropriate value given the current environment. Our secrets file is accessed the same way [block:code] { "codes": [ { "code": "let user = app.config[\"app\", \"mongo-user\"].string\nlet pass = app.config[\"app\", \"mongo-pass\"].string", "language": "swift" } ] } [/block] If the secrets file is not present, these values will be `nil`.