diff --git a/couscous.yml b/couscous.yml index c840f026..e8c82b7f 100644 --- a/couscous.yml +++ b/couscous.yml @@ -20,12 +20,18 @@ menu: getting-started-install-swift-3: text: Install Swift 3 relativeUrl: getting-started/install-swift-3.html + getting-started-quickstart: + text: Manual QuickStart + relativeUrl: getting-started/quickstart.html getting-started-install-toolbox: text: Install Toolbox relativeUrl: getting-started/install-toolbox.html getting-started-hello-world: text: Hello, World relativeUrl: getting-started/hello-world.html + getting-started-xcode: + text: Xcode + relativeUrl: getting-started/xcode.html guide: name: Guide items: @@ -38,3 +44,6 @@ menu: guide-routing: text: Routing relativeUrl: guide/routing.html + guide-config: + text: Config + relativeUrl: guide/config.html diff --git a/getting-started/quickstart.md b/getting-started/quickstart.md index 0c20ae7d..3dd9aeb1 100644 --- a/getting-started/quickstart.md +++ b/getting-started/quickstart.md @@ -48,7 +48,7 @@ And add Vapor as a dependency. Here's how your file will look. #### Package.swift -```Swift +```swift import PackageDescription let package = Package( diff --git a/getting-started/xcode.md b/getting-started/xcode.md new file mode 100644 index 00000000..3a54d4fa --- /dev/null +++ b/getting-started/xcode.md @@ -0,0 +1,45 @@ +--- +currentMenu: getting-started-xcode +--- + +# Xcode + +The first thing you'll probably notice about Vapor and SwiftPM projects in general is that we don't include an Xcode project. In fact, when SwiftPM generates packages, the `.xcodeproj` file is gitignored by default. + +This means we don't have to worry about pbxproj conflicts, and it's easy for different platforms to utilize their own editors. + +## Generate Project + +### Vapor Toolbox + +To generate a new Xcode project for a project, use: + +```bash +vapor xcode +``` + +> If you'd like to automatically open the Xcode project, use `vapor xcode -y` + +### Manual + +To generate a new Xcode project manually. + +```bash +swift package generate-xcodeproj +``` + +Open the project and continue normally. + +## Flags + +For many packages with underlying c-dependencies, users will need to pass linker flags during **build** AND **project generation**. Make sure to consult the guides associated with those dependencies. For example: + +``` +vapor xcode --mysql +``` + +or + +``` +swift package generate-xcodeproj -Xswiftc -I/usr/local/include/mysql -Xlinker -L/usr/local/lib +``` diff --git a/guide/config.md b/guide/config.md new file mode 100644 index 00000000..236c55cf --- /dev/null +++ b/guide/config.md @@ -0,0 +1,185 @@ +--- +currentMenu: guide-config +--- + +# 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. + +```bash +./ +├── Config/ +│ ├── server.json +``` + +And an example of how this might look: + +```JSON +{ + "http": { + "host": "0.0.0.0", + "port": 8080 + } +} +``` + +What that's saying, is that our application should start a single server named 'default' 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: + +```JSON +{ + "http": { + "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["server", "http", "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 `servers.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 +``` + +## 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 folder structure to our Config/ directory. Here's an example of a folder structure that's setup for production and development environments. + +```bash +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. + +```bash +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["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 + +```JSON +{ + "http": { + "host": "0.0.0.0", + "port": 9000 + } +} +``` + +#### `production/servers.json` + +```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: + +```Swift +// will load 0.0.0.0 or 127.0.0.1 based on above config +let host = app.config["servers", "http", "host"].string +// will load 9000, or environment variable port. +let port = app.config["servers", "http", "port"].int +``` + +## 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: + +```bash +--mongo-password=$MONGO_PASSWORD +``` + +would be accessible within your application by using the following: + +```Swift +let mongoPassword = app.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: + +```bash +--config:keys.analytics=124ZH61F +``` + +would be accessible within your application by using the following: + +```Swift +let analyticsKey = app.config["keys", "analytics"].string +```