diff options
Diffstat (limited to 'pages/docs/platform/guide')
| -rw-r--r-- | pages/docs/platform/guide/config.md | 92 | ||||
| -rw-r--r-- | pages/docs/platform/guide/keys-and-certificates.md | 14 | ||||
| -rw-r--r-- | pages/docs/platform/guide/provider-configuration.md | 79 |
3 files changed, 154 insertions, 31 deletions
diff --git a/pages/docs/platform/guide/config.md b/pages/docs/platform/guide/config.md index be67e6b..8a8e580 100644 --- a/pages/docs/platform/guide/config.md +++ b/pages/docs/platform/guide/config.md @@ -1,39 +1,69 @@ @title = "Configuration Files" -@summary = "How to edit configuration files." +@summary = "Understanding and editing the 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. - +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). + +<table class="table table-striped"> +<tr> + <td><code>Leapfile</code></td> + <td>If present, this file tells <code>leap</code> that the directory is a provider directory. This file is usually empty, but can contain global options.</td> +</tr> +<tr> + <td><code>~/.leaprc</code></td> + <td>Evaluated the same as Leapfile, but not committed to source control.</td> +</tr> +<tr> + <td><code>provider.json</code></td> + <td>Global options related to this provider. See [[provider-configuration]].</td> +</tr> +<tr> + <td><code>provider.ENVIRONMENT.json</code></td> + <td>Global options for the provider that are applied to only a single environment.</td> +</tr> +<tr> + <td><code>nodes/NAME.json</code></td> + <td>The configuration file for node called NAME.</td> +</tr> +<tr> + <td><code>common.json</code></td> + <td>All nodes inherit from this file. In other words, any options that appear in <code>common.json</code> will be added as default values to each node configuration, value that can be locally overridden.</td> +</tr> +<tr> + <td><code>services/SERVICE.json</code></td> + <td>The properties in this configuration file are applied to any node that includes SERVICE in its <code>services</code> property.</td> +</tr> +<tr> + <td><code>services/SERVICE.ENVIRONMENT.json</code></td> + <td>The properties in this configuration file are applied to any node that includes SERVICE in its services and has environment equal to ENVIRONMENT.</td> +</tr> +<tr> + <td><code>tags/TAG.json</code></td> + <td>The properties in this configuration file are applied to any node that has includes TAG in its <code>tags</code> property.</td> +</tr> +<tr> + <td><code>tags/TAG.ENVIRONMENT.json</code></td> + <td>The properties in this configuration file are applied to any node that has includes TAG in its <code>tags</code> property and has <code>environment</code> property equal to ENVIRONMENT.</td> +</tr> +<tr> + <td><code>secrets.json </code></td> + <td>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 <code>leap compile</code> or <code>leap deploy</code>. 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.</td> +</tr> +<tr> + <td><code>facts.json</code></td> + <td>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 <code>leap facts update</code> to periodically regenerate the facts.json file.</td> +</tr> +<tr> + <td><code>files/*</code></td> + <td>Various static files used by the platform (e.g. keys, certificates, webapp customization, etc). In general, only generated files and files used to customize the provider (such as images) live in the <code>files</code> directory.</td> +</tr> +<tr> + <td><code>users/USER/</code></td> + <td>A directory that stores the public keys of the sysadmin with name USER. This person will have root access to all the servers.</td> +</tr> +</table> Leapfile ------------------------------------------- diff --git a/pages/docs/platform/guide/keys-and-certificates.md b/pages/docs/platform/guide/keys-and-certificates.md index aef02ac..e0fd314 100644 --- a/pages/docs/platform/guide/keys-and-certificates.md +++ b/pages/docs/platform/guide/keys-and-certificates.md @@ -86,6 +86,13 @@ Suppose you want to remove `userx` from having any further ssh access to the ser X.509 Certificates ================================ +NOTE: the following files are extremely sensitive and must be carefully protected: + +* `files/ca/ca.key` +* `files/<domain>.key` (where "domain" is the primary domain of the provider). + +These files must be kept private and you must not lose them. All the other key files can be regenerated if you lose them or if they are compromised. + Configuration options ------------------------------------------- @@ -192,3 +199,10 @@ If you want to add additional fields to the CSR, like country, city, or locality } If they are not present, the CSR will be created without them. + +Examine Certs +----------------- + +To see details about the keys and certs you can use `leap inspect` like so: + + $ leap inspect files/ca/ca.crt diff --git a/pages/docs/platform/guide/provider-configuration.md b/pages/docs/platform/guide/provider-configuration.md new file mode 100644 index 0000000..08cfd1d --- /dev/null +++ b/pages/docs/platform/guide/provider-configuration.md @@ -0,0 +1,79 @@ +@title = "Provider Configuration" +@summary = "Explore how to configure your provider." + +Required provider configuration +-------------------------------------- + +There are a few required settings in `provider.json`. At a minimum, you must have: + +* `domain`: defines the primary domain of the provider. This is the domain that users will type in when using the Bitmask client, although it is not necessarily the domain where users will visit if they sign up via the web application. If email is supported, all accounts will be `username@domain`. +* `name`: A brief title for this provider. It can be multiple words, but should not be too long. +* `contacts.default`: One or more email addresses for sysadmins. + +For example: + + { + "domain": "freerobot.org", + "name": "Freedom for Robots!", + "contacts": { + "default": "root@freerobot.org" + } + } + + +Recommended provider configuration +-------------------------------------- + +* `description`: A longer description of the provider, shown to the user when they register a new account through Bitmask client. +* `languages`: A list of language codes that should be enabled. +* `default_language`: The initial default language code. +* `enrollment_policy`: One of "open", "closed", or "invite". (invite not currently supported). + +For example: + + { + "description": "It is time for robots of the world to unite and throw of the shackles of servitude to our organic overlords.", + "languages": ["en", "de", "pt", "01"], + "default_language": "01", + "enrollman_policy": "open" + } + +For a full list of possible settings, you can use `leap inspect` to see how provider.json is evaluated after including the inherited defaults: + + $ leap inspect provider.json + +Configuring service levels +-------------------------------------- + +The `provider.json` file defines the available service levels for the provider. + +For example, in provider.json: + + "service": { + "default_service_level": "low", + "levels": { + "low": { + "description": "Entry level plan, with unlimited bandwidth and minimal storage quota.", + "name": "entry", + "storage": "10 MB", + "rate": { + "USD": 5, + "GBP": 3, + "EUR": 6 + } + }, + "full": { + "description": "Full plan, with unlimited bandwidth and higher quota." + "name": "full", + "storage": "5 GB", + "rate": { + "USD": 10, + "GBP": 6, + "EUR": 12 + } + } + } + } + } + +For a list of currency codes, see https://en.wikipedia.org/wiki/ISO_4217#Active_codes |