platform docs: updated commands, removed config items that are no longer supported...
[leap_doc.git] / docs / platform / config.md
index d0b1f6a..3ec2f42 100644 (file)
@@ -1,5 +1,39 @@
 @title = "Configuration Files"
 
+Files
+-------------------------------------------
+
+Here are a list of some of the common files that make up a provider. Except for Leapfile and provider.json, the files are optional. Unless otherwise specified, all file names are relative to the 'provider directory' root (where the Leapfile is).
+
+`Leapfile` -- If present, this file tells `leap` that the directory is a provider directory. This file is usually empty, but can contain global options.
+
+`~/.leaprc` -- Evaluated the same as Leapfile, but not committed to source control.
+
+`provider.json` -- Global options related to this provider.
+
+`provider.ENVIRONMENT.json` -- Global options for the provider that are applied to only a single environment.
+
+`common.json` -- All nodes inherit from this file.
+
+`secrets.json` -- An automatically generated file that contains any randomly generated strings needed in order to deploy. These strings are often secret and should be protected, although any need for a random string or number that is remembered will produce another entry in this file. This file is automatically generated and refreshed each time you run `leap compile` or `leap deploy`. If an entry is no longer needed, it will get removed. If you want to change a secret, you can remove this file and have it regenerated, or remove the particular line item and just those items will be created anew.
+
+`facts.json` -- If some of your servers are running on AWS or OpenStack, you will need to discover certain properties about how networking is configured on these machines in order for a full deploy to work. In these cases, make sure to run `leap facts update` to periodically regenerate the facts.json file.
+
+`nodes/NAME.json` -- The configuration file for node called NAME.
+
+`services/SERVICE.json` -- The properties in this configuration file are applied to any node that includes SERVICE in its `services` property.
+
+`services/SERVICE.ENVIRONMENT.json` -- The properties in this configuration file are applied to any node that includes SERVICE in its services and has environment equal to ENVIRONMENT.
+
+`services/TAG.json` -- The properties in this configuration file are applied to any node that has includes TAG in its `tags` property.
+
+`services/TAG.ENVIRONMENT.json` -- The properties in this configuration file are applied to any node that has includes TAG in its `tags` property and has `environment` property equal to ENVIRONMENT.
+
+`files/*` -- Various static files used by the platform (e.g. keys, certificates, webapp customization, etc).
+
+`users/USER/` -- A directory that stores the public keys of the sysadmin with name USER. This person will have root access to all the servers.
+
+
 Leapfile
 -------------------------------------------
 
@@ -13,8 +47,6 @@ Additionally, you can create a `~/.leaprc` file that is loaded after `Leapfile`
 Platform options:
 
 * `@platform_directory_path` (required). This must be set to the path where `leap_platform` lives. The path may be relative.
-* `@platform_branch`. If set, a check is preformed before running any command to ensure that the currently checked out branch of `leap_platform` matches the value set for `@platform_branch`. This is useful if you have a stable branch of your provider that you want to ensure runs off the master branch of `leap_platform`.
-* `@allow_production_deploy`. By default, you can only deploy to production nodes if the current branch is 'master' or if the provider directory is not a git repository. This option allows you to override this behavior.
 
 Vagrant options:
 
@@ -26,7 +58,7 @@ Logging options:
 * `@log`. If set, all command invocation and results are logged to the specified file. This is the same as the switch `--log FILE`, except that the command line switch will override the value in the Leapfile.
 
 
-Configuration files
+JSON format
 -------------------------------------------
 
 All configuration files, other than `Leapfile`, are in the JSON format. For example:
@@ -195,7 +227,8 @@ Access an element by name:
 Create a new hash table by applying filters:
 
     nodes[:public_dns => true] # all nodes where public_dns == true
-    nodes[:services => 'openvpn', :services => 'tor'] # openvpn OR tor
+    nodes[:services => 'openvpn', 'location.country_code' => 'US'] # openvpn service OR in the US.
+    nodes[[:services, 'openvpn'], [:services, 'tor']]  # services equal to openvpn OR tor
     nodes[:services => 'openvpn'][:tags => 'production']  # openvpn AND production
     nodes[:name => "!bob"] # all nodes that are NOT named "bob"