reorganize

README.md

@@ -12,17 +12,29 @@ What could be more helpful than a guide more interested in a party trick than so
  - [x]   a. domain
  - [x]   b. webhost
  - [x]   c. tools
- - [x] 2. [Public Key Infrastructure](#pki)
+ - [x] 3. [Repository Setup](#repositorySetup)
+ - [x]   a. [DNS](#configureRegistrarDns)
+ - [x]   b. [repo](#createGitRepo)
+ - [x]   c. [clone](#gitClone)
+ - [x] 4. [Hugo](#hugo)
+ - [x]   a. [term](#hugoOpenTerminal)
+ - [x]   a. [winget](#hugoWinget)
+ - [x]   a. [powershell](#hugoPowershell)
+ - [x]   a. [open](#hugoLaunchPowershell)
+ - [x]   a. [init](#hugoInit)
+ - [x] 5. [Web Server](#webroot)
+ - [x]   a. [NginX](#certbotWrapper)
+ - [x]   b. [map webroot](#mapWebroot)
+ - [x] 6. [Public Key Infrastructure](#pki)
  - [x]   a. [putty](#putty)
  - [x]   b. [keygen](#keygen)
  - [x]   c. [pebbleguy.com](#installKey)
  - [x]   d. [pageant-start](#pageantAutoStart)
  - [x]   e. [pageant-key](#pageantNiceToMeetKey)
- - [x] 3. [Rclone](#rclone)
+ - [x] 7. [Rclone](#rclone)
  - [x]   a. [install](#rcloneInstall)
  - [x]   b. [config](#rcloneConfig)
- - [x] 4. [Repository Setup](#repositorySetup)
- - [x]   a. [domain](#configureRegistration)
+ - [x]   b. [deploy](#rcloneDeploy)
 
 ## <a name="intro" id="intro"></a> Introduction
 Why are we doing this?  Static pages are what webservers were built for.  Dynamic pages are largely tools for the developer.  Our world is often a weird broken mess of wonderful things.  There is a project, [squid](https://squid-cache.org), that can magically increase one's internet speed.  The project has been around for nearly 30 years and it isn't magic, they just recognize that most the Internet is thoughtlessly dynamically generated.  A static page is what browsers and servers are designed to handle and they struggle when pages are complicated black boxes[^1].  I am being a little harsh, it isn't that pages are slapped together thoughtlessly, I mean to say that given infinite 'thought' resource only what needed be dynamic would be.
@@ -72,157 +84,63 @@ git push -u origin master
 
 What we see is that the user made sure that they had a DNS record for `kyleguy.rome7.com` then installed `hugo`.  They pulled a copy of the `pebbleguy.com` repository so that they could execute the `certbot-wrapper.sh` to setup a webserver with a certificate signed by a certificate authority.  They then setup a webroot and added a theme to their static site.  Lastly they committed their site contained in a new `git` repository to `git.pebbleguy.com`.  
 
-## <a name="pki" id="pki"></a> Public Key Infrastructure
-
-<a name="putty" id="putty"></a> **Windows does not have ssh-keygen, install it or a replacement:**
-
-Install PuTTY by [Simon Tatham](https://www.chiark.greenend.org.uk/~sgtatham/putty/).  Besides the SSH Terminal `PuTTY` program there is also a ssh key generator program called `PuTTYgen`.
-
-![download-and-install-putty](images/simon-tatham-putty.png)
----
-
-<a name="keygen" id="keygen"></a> **Launch PuTTYgen and generate a key**
-
-![launch-puttygen](images/launch-puttygen.png)
-
-One can generate any number of ssh-keys[^6], RSA, ECDSA, and ED25519 are all good options.  If you select the `EdDSA` radio button you can follow along, but feel free to try one of the other key types I mentioned.  
-
-You then click genrate and move your mouse around a bit in the `Key` window to add a little more noise that what would normally be provided by Windows' entropy pool.
-
-Once the key generates, add a comment and a passphrase.  You may use one of the passwords that you normally give to Microsoft, your bank, and Amazon.  You aren't securing anything super important.  You are just trying to obscure access like you normally would with your financial details.  Is that a tongue in my cheek?  Heh.
-
-The last thing to do is save the private key somewhere.  I just put it on my Desktop.  It is encrypted it isn't going to be useful to anybody without my passphrase.
-
-[^6]: I usually generate 4096-bit RSA keys, but I think there is a bug in the `Raspberry PiOS` SSH confiuration options that the `Raspberry Pi Foundation` employees have yet to resolve.  
-
-
-![generated-private-key](images/generated-private-key.png)
----
-
-<a name="installKey" id="installKey"></a> **Copy the public key to pebbleguy.com**
-
-In the above screenshot you can see the public key in the `PuTTYgen` window.  I will copy my key to pebbleguy.com and you will copy yours.
-You may copy the public key to your clipboard then paste it into your users' `authorized keys`[^7] on pebbleguy.com.  
-
-[^7]: When you sign into pebbleguy.com with SSH it looks at your authorized keys (a list of public keys) to determine what private keys could be used for authentication.  
-The private key stays on my local Windows computer in my Desktop directory.  
-
-To copy your public key[^8], connect to pebbleguy.com and run the below command (make sure to substitue your public key).
-
-[^8]: You can use my public key if you want but I can already sign into my own user using my key so and you won't have my private key so it does not benefit either of us.  `echo '{{YOUR_PUBLIC_KEY}}' |tee -a ~/.ssh/authorized_keys`.
-
-```
-echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGYtvZuiyun9DQe/6xrxby0iQeLy+jE1JKrpgRrHKbrT windows computer rclone key for kyleguy' |tee -a ~/.ssh/authorized_keys
-```
-
-*If you used `ssh-keygen` to generate a key there should be a companion tool, `ssh-copy-id` that can be used to help install the public key on a remote server.*
----
-
-<a name="pageantAutoStart" id="pageantAutoStart"></a> **Add a Pageant shortcut to Windows startup**
-
-The `Rclone` software that we will use to synchronize our website files does not support decryption of private keys.  They do however support requesting an external program to decrypt a key, unfortunatley not the `Windows Credential Store` [^9].  Luckly though, the author of `PuTTY` also wrote a minimal keystore[^10] called `Pageant`.  
-
-We could also use `Gpg4win` which was funded by [Bundesamt f&uuml;r Sicherheit in der Informationstechnik](https://www.bsi.bund.de/DE/Home/home_node.html) (Germany's Federal Office for Information Security).  I would have recommended this path but I didn't have time to explore it fully.
-
-The `Pageant` software is bundled with the `PuTTY` installer so once you install `PuTTY` we can setup `Pageant` to load when Windows loads.
-
-[^9]: Encrypting one's private keys exposes them to some harsh realities.  The `Windows Credential Store` is not well known, lacks documentation, and is riddled with Microsoftisms.  Whenever I write software targeting the Microsoft platform it's these little burdens that end up wasting the most time.  I expect the developers of `Rclone` to face similar roadblocks and it could be an explination for why they do not have native support for decrypting private keys.
+## <a name="repositorySetup" id="repositorySetup"></a> Repository Setup
 
-[^10]: It only supports ssh-keys but with ssh-keys being the defacto key this really doesn't matter.  
+<a name="configureRegistrarDns" id="configureRegistrarDns"></a>**Configure the your domain registrar's DNS**
 
+This assumes you are using the DNS provided by your domain registrar.  Some common registrars are Cloudflare, SquareSpace, Wix, GoDaddy, Gandi, Namecheap, and [others](https://www.icann.org/en/accredited-registrars).  FYI, I listed some bad and some good ones, not a review just blasting.
 
-*If you are using `ssh-keygen` you should also have access to `ssh-agent` which can be configured to aid `Rclone` with encrypted keys.  GNU's `GPG-agent` would do the same thing but I'm not sure what would happen if `Rclone` made a request.*
+Not necessarily the first thing that needs to be accomplished, but if it is done early time can be saved while the DNS provider tries to spread the word out to the internet about your domain.  Add a record for the domain name.  In this example we add `kyleguy.rome7.com`, you only add a record for the subdomain part, `kyleguy`.  You are the decision maker for what domain points to this site.  My site will be hosted on pebbleguy.com so I use a CNAME so that when people go to my site they will know where my site is located.  I did not want a site at `rome7.com` so I am creating a subdomain:
 
-![run-shell-startup](images/shell-startup.png)
+![add-dns-record](images/registrar-example-square.png)
 ---
 
-<a name="pageantNiceToMeetKey" id="pageantNiceToMeetKey"></a> **Tell Pageant about our key**
-
-Using the shortcut we just created, we will provide `Pageant` a way to find our key.
-
-![shell-startup-explorer-window](images/pageant-shortcut.png)
-
-The Windows properties dialog window has a tab, `Shortcut` with a `taget` property that you will set to a value like this:
-```
-"C:\Program Files\PuTTY\pageant.exe" --encrypted C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.ppk
-```
+<a name="createGitRepo" id="createGitRepo"></a> **Create a git repository**
 
-The `--encrypted` flag that tells `pageant` that the key is encrypted and to not prompt for the user to enter a passphrase until it is used for the first time.  This is an stops it from immediately prompting for the passphrase regardless of you using the key.  When `pageant` launches it will put a task manager GUI shortcut in the taskbar.  One can view what keys `pageant` knows about.  Later `Rclone` will be able to ask `pageant` to authenticate ourselves with pebbleguy.com.
+Login to your account on `git.pebbleguy.com`.  Click the add repository button:
 
-![shortcut-properties](images/shortcut-properties.png)
---- 
+![click-add-repo](images/add-repository-button.png)
 
-## <a name="rclone" id="rclone"></a> Rclone
+Then fill out the form.  We will use some predefined options to template our gitignore file and have Gogs initialize the repository for us.
 
-<a name="rcloneInstall" id="rcloneInstall"></a> **Install Rclone**
+![new-repo-settings](images/new-repository.png)
 
-Windows does not have any good generic file synchronization tools.  Nick Craig-Wood wrote a synchronization tool focused on commercial cloud storage products and his team ported it to Windows.  I've never used it but [Rclone](https://rclone.org/) seems well liked and well supported.  Compiled released binaries can be had using the Windows package manager `winget`.
+This is what the mostly empty repository looks like if you were successful:
 
-```
-winget install Rclone.Rclone
-```
+![repo-created-screenshot](images/repository-created.png)
 ---
 
-<a name="rcloneConfig" id="rcloneConfig"></a> **Add an Rclone config for kyleguy**
+<a name="gitClone" id="gitClone"></a> **Get a copy of the repository on your computer**
 
-We can tell `Rclone` about our website and a scheme to update the webserver with changes made to our local static site by providing it configuration directives.  Using a Windows terminal, we can issue this `Rclone` command to generate a config file.  Additional configuration [documentation](https://rclone.org/commands/rclone_config/) is available online.  This will make it easier to provide all the details to `Rclone` every time it is envoked.
-
-By default this will put the config file into your Windows AppData path, `C:\Users\valued-customer\AppData\Roaming\rclone\`.  This is fine, we could also store the config somewhere else like the repository.  I'll include both incase one seems better.  Just don't get clever and store your private key in the repository.  This config has few little security implications, in mine I leak just my pebbleguy.com username, `jb6113`.  As stated earlier we are not leaving unencrypted keys on Windows so we explicitly avoid the directive telling `Rclone` about our key: `key_file "C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.pem"`.  This won't work anyways as our key if formatted as a `.ppk` so the `Rclone` wouldn't be able to read it as-is.  Instead we tell `Rclone` to use an ssh-agent, this is set to true by default but we are going to explicitly set it.
+Open `powershell` or `cmd`:
 
-Default path:
-```
-rclone config create kyleguy sftp host "pebbleguy.com" user "jb6113" key_use_agent "true"
-```
+![run-powershell](images/run-powershell.png)
 
-Copy config to our `Hugo` static site project repository `rclone.conf`:
+You will clone the repository to your desktop, type these commands into the `powershell` terminal.  The output should match closely with the example.  You will want to replace the clone url with your own repository `https://git.pebbleguy.com/{{your_gogs_account_name}}/{{repository_name}}`
 ```
-cp 'C:\Users\valued-customer\AppData\Roaming\rclone\rclone.conf' 'C:\Users\valued-customer\Desktop\kyleguy\'
+cd Desktop
+git clone https://git.pebbleguy.com/kyle/kyleguy
 ```
 
-![create-rclone-configure-file](images/rclone-config-create.png)
----
-
-**Hugo Rclone Deploy**
-
-When we are happy with the results of our work on the local development computer, we can deploy the site to `kyleguy.rome7.com` using the following command snippet:
+![clone-repository](images/clone-project-to-desktop.png)
 
-```
-cd Desktop\kyleguy
-rclone sync --config rclone.conf web\public\ kyleguy:/mnt/external/projects/kyleguy/web/public/
-```
-![rclone-sync](images/rclone-sync.png)
+With the repository cloned to your desktop successfully, you should be able to use the `Windows file explorer` to view the files:
 
-The first time we do this `Pageant` will prompt us to provide the passphrase for our encrypted private key:
-![pageant-passphrase-prompt](images/passphrase-promt.png)
+![file-explorer](images/file-explorer.png)
 ---
 
-**Just in-case you get a permission denied**
-
-![troubleshoot-permission-denied](images/permission-denied.png)
-
-This is just because your user is not allowed to write files to the target location.  You'll log into pebbleguy.com and use `ls -lathr` on the directory you are trying to copy into and look at the permissions.  Right now it is out-of-scope to explain users and permissions.  I expect that with so many users "helping" eachother out that we should all be familiar with the side effects of what happens when we accidentally forget about permissions.  In general all the admin users have been added to a group, `www-data`.  By default files created by a user are owned by that user.  This is the root cause of these accidents but is a sane method for file creation.  We should learn to be cognizant of the environment we are in and not expect that anyone but ourselves are able to know what our intentions were.
-
-
-## a place called home, or maybe webroot
-Base directory.  Home.  Root.  C Drive.  What other names are there? Maybe `A:` or `/`.  The place that is the container for the stuff.  Or the directory that holds all the files.  Folders if you like that better.  The `webroot` is a name that does not mean anything except for when you care about it.  If it were your job to organize a party you'd probably pick a place and tell everyone to meet there.  For this tiny amount of time that location is special.  It is ground zero for where the party will happen.  People who aren't at the specified location aren't at the party.  Your party isn't the only party.  In fact it might not even be the only party at the location that you picked.  The point is that you picked a location made it special because you said it was.  This is the same for a webroot.  You are just picking some arbitrary location on a disk and you are going to tell everyone if they want to party at your website they need to go there.  When you follow the instructions for the site setup you will need to tell `NginX` about this location.  I am going to pick the location and we are going to put some files there to serve up at the party.  How long can I draw out this metaphore?  Forever.
+## <a name="hugo" id="hugo"></a> **Install Hugo**
 
-Our `webroot` is going to be `/mnt/external/websites/kyleguy.rome7.com`.  We are going to store files in an adjacent directory, further explained when we do the site setup.  This directory that actually contains all the `.html` files and cool pictures of cats is going to be `/mnt/external/projects/kyleguy/web/public`.  And `/mnt/external/projects/kyleguy`  that is this repository.  There is a copy of this `README.md` in `/mnt/external/projects/kyleguy/README.md`.  Whoa trippy.  Lets put this `README.md` there.
-
-```
-cd /mnt/external/projects
-git clone https://git.pebbleguy.com/kyle/kyleguy
-```
-
-Public does not exist yet.  Let's create it.  We are hosting a static site generated by a tool called `hugo`.  We need `hugo`.  One would be better off developing their site on their computer.  So let's use Windows because I loath the OS and like maximum pain.
+Hugo is our static site generator.  We will install it on a local Windows computer.
 
 First up is to install Hugo using the windows package manager, `winget`.
 
-**Open a terminal**
+<a name="hugoOpenTerminal" id="hugoOpenTerminal"></a> **Open a terminal**
 
 ![run-powershell](images/run-powershell.png)
 ---
 
-**Download and install hugo**
+<a name="hugoWinget" id="hugoWinget"></a> **Download and install hugo**
 
 ```
 winget install Hugo.Hugo.Extended
@@ -231,8 +149,9 @@ winget install Hugo.Hugo.Extended
 ![install-hugo-with-winget](images/winget-install-hugo.png)
 ---
 
-**uh-oh we want to be in a repository but we do we have one?**
-There are instructions to setup the repository in this  guide, go there when you get to a stopping point there come back here.
+We will need the steps from the [repository setup](#gitClone) portion of the guide completed before we continue.
+
+*This next bit will fail, but we document it here in case you run into it.*
 
 Wow cool, we have a copy of the `kyleguy` repository on our windows computer.  We can initilize a `hugo` static site.
 
@@ -240,20 +159,21 @@ Windows is really cool they have a feature where they print red text until you c
 ![red-windows-text-good-job](images/windows-red-text-feature.png)
 ---
 
-
 Actually this is a good break, because we cannot use Windows Powershell we need Powershell.  Yeh.  I cannot fix that.  Pretty wild.  There is a difference.  We will jump back here, but we need to install Powershell first.
 
-**Install Powershell**
+<a name="hugoPowershell" id="hugoPowershell"></a> **Install Powershell**
 
 Open up that terminal, then use `winget` to install `powershell`.
 ![install-powershell-with-winget](images/windows-powershell-err-powershell.png)
 ---
 
-**back to: uh-oh we want to be in a repository but we do we have one?**
+<a name="hugoLaunchPowershell" id="hugoLaunchPowershell"></a> **Launch Powershell**
+
 We launch `powershell` a little differently:
 ![run-other-powershell](images/run-the-other-powershell.png)
 
-**Initilize a static page using hugo**
+<a name="hugoInit" id="hugoInit"></a> **Initilize a static page using hugo**
+
 Let us initilize the files needed for our website:
 ```
 cd Desktop/kyleguy
@@ -292,14 +212,31 @@ git commit -m'added a hugo site'
 git push
 ```
 
-## site setup
-You are going to need a domain, either buy one or be a person whom already has a domain.  We are going to host our site on `pebbleguy.com` using the `NginX` ("engine x") web server.  We will create a site configuration file with SSL using a tool, `certbot-wapper.sh`.  This script is part of the [pebbleguy repository](https://git.pebbleguy.com/Dan/pebbleguy.com/src/master/scripts/certbot-wrapper.sh).  Login to your account on `pebbleguy.com` using Secure Shell (SSH) or ask Kyle, Chris, Daniel, or Emma for help.  If you are one of those people, hello!  Download the `pebbleguy.com` repository so you have access to the script and run `certbot-wrapper.sh` to have it create the `NginX` config file for your site:
+## <a name="webroot" id="webroot"></a> A place called home, or maybe webroot
+
+`Webroot` is jargon that we should try to use when talking about websites.  It refers to a directory[^11] that is arbitrarily choosen and then named `webroot`.
+
+[^11]: Base directory.  Home.  Root.  C Drive.  What other names are there? Maybe `A:` or `/`.  The place that is the container for the stuff.  Or the directory that holds all the files.  Folders if you like that better.  The `webroot` is a name that does not mean anything except for when you care about it.  If it were your job to organize a party you'd probably pick a place and tell everyone to meet there.  For a momemnt that location is special.  It is root, ground zero for where the party will happen.  Your party isn't the only party, in fact it might not even be the only party at the location that you picked.  The point is that you picked a location made it special because you said it was.  This is the same for a `webroot`.  You are just picking some arbitrary location on a disk and you are going to tell everyone if they want to party at your website they need to go there.  When you follow the instructions for the site setup you will need to tell `NginX` about this location.  I am going to pick the location and we are going to put some files there to serve up at the party.  How long can I draw out this metaphore?  Forever.
+
+Our `webroot` is going to be `/mnt/external/websites/kyleguy.rome7.com`.  We are going to store files in an adjacent directory[^12], `/mnt/external/projects/kyleguy/web/public`, further explained when we do the site setup.
+
+[^12]: The directory that actually contains all the `.html` files and cool pictures of cats is going to be outside the normal `webroot`.  This is pretty common on pebbleguy.com.  One might consider `/mnt/external/websites/kyleguy.rome7.com` or `/mnt/external/projects/kyleguy/web/public` as `webroot`, it really depends on the perspective of the person asking if the term is appropriate.
+
+You are going to need a domain, either buy one or be a person whom already has a domain.  We are going to host our site on `pebbleguy.com` using the `NginX` ("engine x") web server.  We will create a site configuration file with SSL using a tool, `certbot-wapper.sh`[^13].
+
+[^13]: This script is part of the [pebbleguy repository](https://git.pebbleguy.com/Dan/pebbleguy.com/src/master/scripts/certbot-wrapper.sh).
+
+<a name="certbotWrapper" id="certbotWrapper"></a> **Run `certbot-wrapper.sh`:**
+
+Login to your account on `pebbleguy.com` using Secure Shell (SSH) or ask Kyle, Chris, Daniel, or Emma for help.  If you are one of those people, hello!  Download the `pebbleguy.com` repository so you have access to the script and run `certbot-wrapper.sh` to have it create the `NginX` config file for your site:
 ```
 git clone https://git.pebbleguy.com/Dan/pebbleguy.com
 cd pebbleguy.com/scripts
 ./certbot-wrapper.sh -h kyleguy.rome7.com -u kyle
 ```
 
+*You can skip the next bit to [map webroot](#mapWebroot). We just explain some of the patterns we follow on pebbleguy.com*
+
 This should create a configuration file either on the external disk or primary disk depending on if `pebbleguy.com` is in `Read-Only` or `Read-Write` mode.  More info on that [here](https://git.pebbleguy.com/Dan/pebbleguy.com#persistent-storage).  The locations are either `/mnt/external/live-server-configs/for-nginx/sites-enabled/kyleguy-web.conf` or `/etc/nginx/sites-enabled/kyleguy-web.conf`.
 
 Keep those file locations in mind for later.
@@ -344,56 +281,142 @@ gogs  live-server-configs  lost+found  projects  websites
 ```
 
 You will put your site repository into the `projects` directory.  You will also notice a `websites` directory.  You could put your website there, but you'd get caught in an organizational nightmare.  Instead we will put a sort of shortcut into the `websites` directory that points to the actual website directory that is contained in our repository.  This way we don't ever need to come back to this terminal on `pebbleguy.com` to mess around with our files ever again, probably.
+
+<a name="mapWebroot" id="mapWebroot"></a> **Map webroot**
+
 ```
-username@pebbleguy:/mnt/external $ cd /mnt/external
-username@pebbleguy:/mnt/external $ ls
-gogs  live-server-configs  lost+found  projects  websites
 username@pebbleguy:/mnt/external $ sudo ln -s /mnt/external/projects/kyleguy/web/public/ /mnt/external/websites/kyleguy.rome7.com
 username@pebbleguy:/mnt/external $ ls /mnt/external/websites
 emma-kac  gogs-webhooks  KingsAndChaos  kyleguy.rome7.com  shootGame  www.pebbleguy.com
 ```
 
-## <a name="repositorySetup" id="repositorySetup"></a> Repository Setup
+## <a name="pki" id="pki"></a> Public Key Infrastructure
 
-<a name="configureRegistrarDns" id="configureRegistrarDns"></a>**Configure the your domain registrar's DNS**
+<a name="putty" id="putty"></a> **Windows does not have ssh-keygen, install it or a replacement:**
 
-This assumes you are using the DNS provided by your domain registrar.  Some common registrars are Cloudflare, SquareSpace, Wix, GoDaddy, Gandi, Namecheap, and [others](https://www.icann.org/en/accredited-registrars).  FYI, I listed some bad and some good ones, not a review just blasting.
+Install PuTTY by [Simon Tatham](https://www.chiark.greenend.org.uk/~sgtatham/putty/).  Besides the SSH Terminal `PuTTY` program there is also a ssh key generator program called `PuTTYgen`.
 
-Not necessarily the first thing that needs to be accomplished, but if it is done early time can be saved while the DNS provider tries to spread the word out to the internet about your domain.  Add a record for the domain name.  In this example we add `kyleguy.rome7.com`, you only add a record for the subdomain part, `kyleguy`.  You are the decision maker for what domain points to this site.  My site will be hosted on pebbleguy.com so I use a CNAME so that when people go to my site they will know where my site is located.  I did not want a site at `rome7.com` so I am creating a subdomain:
+![download-and-install-putty](images/simon-tatham-putty.png)
+---
 
-![add-dns-record](images/registrar-example-square.png)
+<a name="keygen" id="keygen"></a> **Launch PuTTYgen and generate a key**
+
+![launch-puttygen](images/launch-puttygen.png)
+
+One can generate any number of ssh-keys[^6], RSA, ECDSA, and ED25519 are all good options.  If you select the `EdDSA` radio button you can follow along, but feel free to try one of the other key types I mentioned.  
+
+You then click genrate and move your mouse around a bit in the `Key` window to add a little more noise that what would normally be provided by Windows' entropy pool.
+
+Once the key generates, add a comment and a passphrase.  You may use one of the passwords that you normally give to Microsoft, your bank, and Amazon.  You aren't securing anything super important.  You are just trying to obscure access like you normally would with your financial details.  Is that a tongue in my cheek?  Heh.
+
+The last thing to do is save the private key somewhere.  I just put it on my Desktop.  It is encrypted it isn't going to be useful to anybody without my passphrase.
+
+[^6]: I usually generate 4096-bit RSA keys, but I think there is a bug in the `Raspberry PiOS` SSH confiuration options that the `Raspberry Pi Foundation` employees have yet to resolve.  
+
+
+![generated-private-key](images/generated-private-key.png)
 ---
 
-**Create a git repository**
+<a name="installKey" id="installKey"></a> **Copy the public key to pebbleguy.com**
 
-Login to your account on `git.pebbleguy.com`.  Click the add repository button:
+In the above screenshot you can see the public key in the `PuTTYgen` window.  I will copy my key to pebbleguy.com and you will copy yours.
+You may copy the public key to your clipboard then paste it into your users' `authorized keys`[^7] on pebbleguy.com.  
 
-![click-add-repo](images/add-repository-button.png)
+[^7]: When you sign into pebbleguy.com with SSH it looks at your authorized keys (a list of public keys) to determine what private keys could be used for authentication.  
+The private key stays on my local Windows computer in my Desktop directory.  
 
-Then fill out the form.  We will use some predefined options to template our gitignore file and have Gogs initialize the repository for us.
+To copy your public key[^8], connect to pebbleguy.com and run the below command (make sure to substitue your public key).
 
-![new-repo-settings](images/new-repository.png)
+[^8]: You can use my public key if you want but I can already sign into my own user using my key so and you won't have my private key so it does not benefit either of us.  `echo '{{YOUR_PUBLIC_KEY}}' |tee -a ~/.ssh/authorized_keys`.
 
-This is what the mostly empty repository looks like if you were successful:
+```
+echo 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGYtvZuiyun9DQe/6xrxby0iQeLy+jE1JKrpgRrHKbrT windows computer rclone key for kyleguy' |tee -a ~/.ssh/authorized_keys
+```
 
-![repo-created-screenshot](images/repository-created.png)
+*If you used `ssh-keygen` to generate a key there should be a companion tool, `ssh-copy-id` that can be used to help install the public key on a remote server.*
 ---
 
-**Get a copy of the repository on your computer**
+<a name="pageantAutoStart" id="pageantAutoStart"></a> **Add a Pageant shortcut to Windows startup**
 
-Open `powershell` or `cmd`:
+The `Rclone` software that we will use to synchronize our website files does not support decryption of private keys.  They do however support requesting an external program to decrypt a key, unfortunatley not the `Windows Credential Store` [^9].  Luckly though, the author of `PuTTY` also wrote a minimal keystore[^10] called `Pageant`.  
 
-![run-powershell](images/run-powershell.png)
+We could also use `Gpg4win` which was funded by [Bundesamt f&uuml;r Sicherheit in der Informationstechnik](https://www.bsi.bund.de/DE/Home/home_node.html) (Germany's Federal Office for Information Security).  I would have recommended this path but I didn't have time to explore it fully.
 
-You will clone the repository to your desktop, type these commands into the `powershell` terminal.  The output should match closely with the example.  You will want to replace the clone url with your own repository `https://git.pebbleguy.com/{{your_gogs_account_name}}/{{repository_name}}`
+The `Pageant` software is bundled with the `PuTTY` installer so once you install `PuTTY` we can setup `Pageant` to load when Windows loads.
+
+[^9]: Encrypting one's private keys exposes them to some harsh realities.  The `Windows Credential Store` is not well known, lacks documentation, and is riddled with Microsoftisms.  Whenever I write software targeting the Microsoft platform it's these little burdens that end up wasting the most time.  I expect the developers of `Rclone` to face similar roadblocks and it could be an explination for why they do not have native support for decrypting private keys.
+
+[^10]: It only supports ssh-keys but with ssh-keys being the defacto key this really doesn't matter.  
+
+
+*If you are using `ssh-keygen` you should also have access to `ssh-agent` which can be configured to aid `Rclone` with encrypted keys.  GNU's `GPG-agent` would do the same thing but I'm not sure what would happen if `Rclone` made a request.*
+
+![run-shell-startup](images/shell-startup.png)
+---
+
+<a name="pageantNiceToMeetKey" id="pageantNiceToMeetKey"></a> **Tell Pageant about our key**
+
+Using the shortcut we just created, we will provide `Pageant` a way to find our key.
+
+![shell-startup-explorer-window](images/pageant-shortcut.png)
+
+The Windows properties dialog window has a tab, `Shortcut` with a `taget` property that you will set to a value like this:
 ```
-cd desktop
-git clone https://git.pebbleguy.com/kyle/kyleguy
+"C:\Program Files\PuTTY\pageant.exe" --encrypted C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.ppk
 ```
 
-![clone-repository](images/clone-project-to-desktop.png)
+The `--encrypted` flag that tells `pageant` that the key is encrypted and to not prompt for the user to enter a passphrase until it is used for the first time.  This is an stops it from immediately prompting for the passphrase regardless of you using the key.  When `pageant` launches it will put a task manager GUI shortcut in the taskbar.  One can view what keys `pageant` knows about.  Later `Rclone` will be able to ask `pageant` to authenticate ourselves with pebbleguy.com.
 
-With the repository cloned to your desktop successfully, you should be able to use the `Windows file explorer` to view the files:
+![shortcut-properties](images/shortcut-properties.png)
+--- 
 
-![file-explorer](images/file-explorer.png)
+## <a name="rclone" id="rclone"></a> Rclone
+
+<a name="rcloneInstall" id="rcloneInstall"></a> **Install Rclone**
+
+Windows does not have any good generic file synchronization tools.  Nick Craig-Wood wrote a synchronization tool focused on commercial cloud storage products and his team ported it to Windows.  I've never used it but [Rclone](https://rclone.org/) seems well liked and well supported.  Compiled released binaries can be had using the Windows package manager `winget`.
+
+```
+winget install Rclone.Rclone
+```
 ---
+
+<a name="rcloneConfig" id="rcloneConfig"></a> **Add an Rclone config for kyleguy**
+
+We can tell `Rclone` about our website and a scheme to update the webserver with changes made to our local static site by providing it configuration directives.  Using a Windows terminal, we can issue this `Rclone` command to generate a config file.  Additional configuration [documentation](https://rclone.org/commands/rclone_config/) is available online.  This will make it easier to provide all the details to `Rclone` every time it is envoked.
+
+By default this will put the config file into your Windows AppData path, `C:\Users\valued-customer\AppData\Roaming\rclone\`.  This is fine, we could also store the config somewhere else like the repository.  I'll include both incase one seems better.  Just don't get clever and store your private key in the repository.  This config has few little security implications, in mine I leak just my pebbleguy.com username, `jb6113`.  As stated earlier we are not leaving unencrypted keys on Windows so we explicitly avoid the directive telling `Rclone` about our key: `key_file "C:\Users\valued-customer\Desktop\windows-rclone-key-for-kyleguy.pem"`.  This won't work anyways as our key if formatted as a `.ppk` so the `Rclone` wouldn't be able to read it as-is.  Instead we tell `Rclone` to use an ssh-agent, this is set to true by default but we are going to explicitly set it.
+
+Default path:
+```
+rclone config create kyleguy sftp host "pebbleguy.com" user "jb6113" key_use_agent "true"
+```
+
+Copy config to our `Hugo` static site project repository `rclone.conf`:
+```
+cp 'C:\Users\valued-customer\AppData\Roaming\rclone\rclone.conf' 'C:\Users\valued-customer\Desktop\kyleguy\'
+```
+
+![create-rclone-configure-file](images/rclone-config-create.png)
+---
+
+<a name="rcloneDeploy" id="rcloneDeploy"></a> **Hugo Rclone Deploy**
+
+When we are happy with the results of our work on the local development computer, we can deploy the site to `kyleguy.rome7.com` using the following command snippet:
+
+```
+cd Desktop\kyleguy
+rclone sync --config rclone.conf web\public\ kyleguy:/mnt/external/projects/kyleguy/web/public/
+```
+![rclone-sync](images/rclone-sync.png)
+
+The first time we do this `Pageant` will prompt us to provide the passphrase for our encrypted private key:
+![pageant-passphrase-prompt](images/passphrase-promt.png)
+---
+
+**Just in-case you get a permission denied**
+
+![troubleshoot-permission-denied](images/permission-denied.png)
+
+This is just because your user is not allowed to write files to the target location.  You'll log into pebbleguy.com and use `ls -lathr` on the directory you are trying to copy into and look at the permissions.  Right now it is out-of-scope to explain users and permissions.  I expect that with so many users "helping" eachother out that we should all be familiar with the side effects of what happens when we accidentally forget about permissions.  In general all the admin users have been added to a group, `www-data`.  By default files created by a user are owned by that user.  This is the root cause of these accidents but is a sane method for file creation.  We should learn to be cognizant of the environment we are in and not expect that anyone but ourselves are able to know what our intentions were.
+