Document the SSL cert setup and validation process

README.md

@@ -89,7 +89,7 @@ If you don't already have one, the first step is to create your AWS root account
 
 The access keys will allow the tool to operate under your root (or super-admin) account in order to set up SSO operation. At the end of it all, the tool can delete the access keys for you.
 
-1. Follow the instructions to [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+1. Follow the instructions to [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/get-started-install.html).
 2. Log into your root account (or super-admin account if you have one).
 3. Click on the account name in the upper right-hand corner and select 'Security credentials'.
 4. Under the 'Access keys' section, select 'Create access key'. You may get a warning; if you do, acknowledge and click next.
@@ -243,7 +243,7 @@ cloudsite update your-domain.com
 
 - [`cleanup`](#cloudsite-cleanup): Attempts to fully delete partially deleted sites in the 'needs to be cleaned up' state.
 - [`configuration`](#cloudsite-configuration): Command group for managing the cloudsite CLI configuration.
-- [`create`](#cloudsite-create): Creates a new website, setting up infrastructure and copying content.
+- [`create`](#cloudsite-create): Creates a new website, setting up infrastructure and copying content. The first time you launch a new domain, Cloudsite will create an SSL certificate for the domain as necessary. If a new SSL certificate is created, the creation process will exit and you'll be given instructions on how to verify the SSL certificate. Once verification is complete, re-run the create command.
 - [`destroy`](#cloudsite-destroy): Destroys the named site. I.e., deletes all cloud resources associated with the site.
 - [`detail`](#cloudsite-detail): Prints details for the indicated site.
 - [`document`](#cloudsite-document): Generates self-documentation in Markdown format.
@@ -332,7 +332,7 @@ Displays the current configuration.
 
 `cloudsite create <options> <apex-domain>`
 
-Creates a new website, setting up infrastructure and copying content.
+Creates a new website, setting up infrastructure and copying content. The first time you launch a new domain, Cloudsite will create an SSL certificate for the domain as necessary. If a new SSL certificate is created, the creation process will exit and you'll be given instructions on how to verify the SSL certificate. Once verification is complete, re-run the create command.
 
 ##### `create` options
 
@@ -387,7 +387,6 @@ Generates self-documentation in Markdown format.
 
 |Option|Description|
 |------|------|
-|`--prefix`|A string to prefix to the standard output.|
 |`--section-depth`|An integer indicating initial header 'depth', where '1' means start with an 'H1/#' section header, '2' means start with an 'H2/##' section header, etc. This is useful when the documentation is embedded in other docs.|
 |`--title`|The title of the top level section header.|
 

site/docs/getting-started/_category_.yml → site/docs/get-started/_category_.yml

@@ -1,5 +1,5 @@
-label: Getting started
-position: 3
+label: Get started
+position: 2
 link:
   type: generated-index
   description: Details on installing, configuring, and running the cloudsite tool.

site/docs/getting-started/authentication.md → site/docs/get-started/authentication.md

@@ -1,12 +1,12 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 description: Instructions on authenticating Cloudsite with AWS.
 ---
 # Authentication
 
-Cloudsite works by setting up and managing infrastructure on the AWS cloud. In order to do this, Cloudsite uses local _credentials_ which allow it to act on your behalf.
+Cloudsite works by setting up and managing infrastructure on the AWS cloud. Cloudsite needs an account and account credentials to do this. We set up the credentials in a two step process.
 
-We work with two kinds of credentials. Initially, we create _access keys_ because it's easy. Cloudsite then uses those access keys to set up _single sign-on (SSO) authentication_ which creates much more secure time limited credentials. The original access keys are then deleted.
+First, we create _access keys_. Cloudsite then uses the access keys and your AWS root account to set up a dedicated account with limited permissions using _single sign-on (SSO) authentication_. This is much more secure, and once set up, Cloudsite will delete the access keys.
 
 The time limited SSO credentials are only valid for a set period of time (4 hours by default). This means that even if your computer is compromised, your AWS account is still safe so long as the credentials have expired. And even if an attacker manages to get ahold of valid SSO credentials, their access will still end when the SSO session times out.
 
@@ -32,9 +32,9 @@ If you are using Cloudsite for your own websites, it's fine to use your personal
 
 ## Initial authentication with access keys
 
-As [discussed up top](#top), we start by creating access keys. Access keys are easier to setup than SSO authentication, but because they grant permanent access to your account, they are less secure. So we use access keys for the initial setup, and then Cloudsite will delete them once [single sign-on authentication](#single-sign-on-authentication) is set up.
+As [discussed up top](#top), we start by creating access keys. Access keys are easier to setup than SSO authentication, but because they grant permanent access to your account, they are less secure. These keys will be deleted once [single sign-on authentication](#single-sign-on-authentication) is set up.
 
-1. Follow the instructions to [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+1. Follow the instructions to [Install or update to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/get-started-install.html).
 2. Log into AWS as the root user or, if you have one, a super-admin account.
 3. Click on the account name in the upper right-hand corner and select 'Security credentials'.
 4. Under the 'Access keys' section, select 'Create access key'. Acknowledge and click 'Next' if you get a warning.

site/docs/get-started/configuration.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 4
+description: A brief rundown on configuring Cloudsite.
+---
+# Configuration
+
+To set the default profile and output preferences, run:
+```bash
+cloudsite configuration setup-local
+```
+
+- The 'AWS SSO profile' should match the profile created in the [SSO authentication setup](/docs/get-started/authentication#single-sign-on-authentication). If you used the default profile name, then just accept the default.
+- Cloudsite supports four output formats. The 'json' and 'yaml' are data formats and most useful for programmatic use of the CLI. The 'termnial' and 'text' are intended for humans, with the 'terminal' format just being the colored version of 'text'.
+- Select whether you want quite mode or not by default. As the tool explains, quite mode only outputs the results of a command whereas non-quiet mode will output updates along the way. Non-quite mode is aimed at humans and quite mode is more useful for programmatic usage.
+
+You can override these defaults for any single Cloudsite invocation with the `--format` and `--quiet` options. E.g.:
+```bash
+cloudsite --format json --quiet create some-domain.com --source-path ./website
+```

site/docs/get-started/installation.md

@@ -0,0 +1,85 @@
+---
+sidebar_position: 2
+description: Instructions on installing Cloudsite.
+---
+# Installation
+
+If you're familiar with Node and terminals and all that, just install cloudsite with:
+```bash
+npm i -g cloudsite
+```
+
+If that doesn't work, or you're just not sure what to do, then keep reading.
+
+## Terminal commands
+
+Cloudsite is a _terminal program_ meaning you interface with the tool by typing commands in a _command terminal_. Even if you're not familiar with terminals and the command line, just follow the instructions.
+
+### Opening a terminal on Mac
+
+Select 'Applications' => 'Utilities' => 'Terminal'
+
+### Opening a terminal on Windows
+
+Use the shortcut '⊞ Windows key + X', and then select Windows Terminal (Admin)
+
+## Node and NPM
+
+You will need Node and a Node package manager installed in order to install and run Cloudsite.
+
+### Checking for Node and NPM
+
+To see if Node and NPM are installed, open a terminal and execute:
+```bash
+node -v
+```
+
+If you get something like 'v21.5.0', then Node is installed. If you get a 'command not found' error, then node is not installed.
+
+Node and NPM usually come together, but to check for NPM specifically, execute:
+```bash
+npm -v
+```
+
+### Install Node and NPM
+
+NPM is a package manager installed with Node; hence 'Node Package Manager' or 'NPM'. Cloudsite is distributed as an NPM package and runs on Node.
+
+There are many different ways to install Node/NPM and advanced users can refer to the [Node download and install page](https://nodejs.org/en/download/package-manager). For users who just want to install Cloudsite, we recommend what we believe to be the simplest methods below:
+
+#### Install Node/NPM on Mac
+
+__Option 1__: Homebrew
+
+If you have Homebrew installed, open a terminal and run:
+```bash
+brew install node@latest
+```
+
+__Option 2__: PKG installer
+
+If you don't have or don't know what Homebrew is, don't worry. Just go to the [Node download page](https://nodejs.org/en/download) and to download and install the Node package.
+
+#### Install Node/NPM on Windows
+
+Go to the [Node download page](https://nodejs.org/en/download) to download and install Node+NPM.
+
+#### Install Node/NPM on Linux
+
+__Option 1__: Install using the system package manager
+
+If you're using Linux and you know what a package manager is, Node is almost certainly offered.
+
+__Option 2__: Install using NVM
+
+NVM or the 'Node version manager' is like a mini-package manager specifically to allow you to install, manage, and select different versions of Node. To install using the latest NVM, refer to the [Node package manager installation page](https://nodejs.org/en/download/package-manager) and select 'Linux' as the OS and 'NVM' as the package manager.
+
+## Install Cloudsite
+
+Once NPM is installed, simply type:
+```bash
+npm install --global cloudsite
+```
+
+You're now ready to [set up authentication](/docs/get-started/authentication).
+

site/docs/get-started/overview.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+description: An overview of getting started.
+---
+
+# Overview
+
+To get going with Cloudsite:
+
+1. [Install Cloudsite](./installation#install-cloudsite), [installing Node and NPM](./installation#install-node-and-npm) if necessary.
+2. [Set up AWS authentication.](./authentication)
+3. [Configure Cloudsite.](./configuration)
+4. [Launch your first site.](./your-first-site)

site/docs/getting-started/your-first-site.md → site/docs/get-started/your-first-site.md

@@ -1,22 +1,22 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 description: A quick example of launching a site.
 ---
 # Your First Site
 
 ## Register your domain name
 
-While there are ways to host a website without a domain name, Cloudsite currently does require a domain name. The site will hosted under the apex domain and the 'www' sub-domain.
+Cloudsite requires a domain name so your website has someplace to live.
 
-If you don't have a domain name already, you'll first need to register a domain name. Refer to our [domain name selection guide](/docs/user-guides/domain-name-selection) for ideas on finding a good name. If you register the domain with AWS Route 53, then that should be all you need to do as far as the domain name goes.
+If you don't have a domain name already, you'll first need to register a domain name. Refer to our [domain name selection guide](/docs/user-guides/domain-name-selection) for ideas on finding a good name. To keep things simple, we strongly recommend registering your domain name using [Route 53](https://aws.amazon.com/route53/).
 
 If you already have a domain name, then refer to our [domain name configuration guide](/docs/user-guides/domain-name-management) on how to either [transfer a domain to Route 53](/docs/user-guides/domain-name-management#transfer-a-domain-to-route-53) or how to [configure 3rd party registered domains](/docs/user-guides/domain-name-management#configure-3rd-party-registered-domains).
 
 ## Prepare your site files
 
 Cloudsite hosts primarily [_static websites_](/docs/user-guides/static-websites), with some support for specific dynamic content and actions via plugins. Basically a static site is one defined entirely by a set of files. There are methods to turn dynamic websites, like a WordPress site, into static sites and we cover a number of specific options in the [website development guides](/docs/category/website-development).
 
-Regardless of the method used to generate the static files, at the end of the day, you end up with a collection of files in a director. We call those files the _source files_ which are all collected and stored in a single _source folder_. For our example, we'll have a single source file:
+Regardless of the method used to generate the static files, at the end of the day, you end up with a collection of files in a folder. We call those files the _source files_ which are all collected and stored in a single _source folder_. If you don't have site files already, then create a source folder (call it 'website' or something) and create a single `index.html` file in the source folder with the following contents:
 ```html
 <!DOCTYPE html>
 <html lang="en">
@@ -30,17 +30,6 @@ Regardless of the method used to generate the static files, at the end of the da
 </html>
 ```
 
-We'll save this file in a file called `index.html` in a folder `website` just under the home folder. This is our source folder and it looks like:
-```
-- $HOME
-  | 
-  - website
-    |
-    - index.html
-```
-
-Obviously your real website will have a lot more files, but the procedure is the same whether we're dealing with one or one thousand files. The important thing is that all the source files be placed in a source folder.
-
 ## Deploy your site
 
 Deploying is as simple as:
@@ -53,7 +42,7 @@ cloudsite create your-domain.com --source-path ~/website
 
 Where `--source-path` takes the path to your source folder. The path may be relative or absolute.
 
-The first time you launch a particular domain, you might get an error about validating the SSL certificate. If you read through the error information, you'll see a web address where you can verify the SSL certificate. Navigate to this address, then find and click the 'Create records in Route 53' button. After giving it a little time, just re-run the `cloudsite create` command.
+The first time you launch a particular domain, Cloudsite will create an SSL certificate for the domain if there isn't already one. This SSL certificate must be verified before further setup can happen. Follow the instructions as provided by Cloudsite to verify the SSL certificate and then re-run the create command once the certificate is verified.
 
 ## Updating your site
 
@@ -63,7 +52,6 @@ At some point, your site will probably need to be updated. In our example, let's
 cloudsite update your-domain.com --do-content
 ```
 
-
 ## Summary
 
 That's about it. If you don't have a static website already, we suggest you look at the [website development guides](/docs/category/website-development) and go from there. You can also refer to the [common use cases guide](/docs/user-guides/common-use-cases) for an idea of what kinds of things you can do with the tool.