From 307d871cad8b26680f0207e5d7106dd23df90159 Mon Sep 17 00:00:00 2001
From: Maddy Guthridge <hello@maddyguthridge.com>
Date: Tue, 15 Oct 2024 19:08:56 +1100
Subject: [PATCH] Document new setup process

---
 design/Setup.md                    | 28 ++++++++++++++++++----------
 src/lib/server/data/localConfig.ts |  3 +++
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/design/Setup.md b/design/Setup.md
index 294c0ff1..dfc7579f 100644
--- a/design/Setup.md
+++ b/design/Setup.md
@@ -1,12 +1,20 @@
 # Setup process
 
-1. User specifies a data repository URL, which is then cloned.
-2. If the repo is empty, some default data is configured:
-    * `config.json` with the site's default configuration
-    * `.gitignore` with a simple gitignore to ignore the local configuration
-3. Otherwise, the `.gitignore` is checked to ensure that `config.local.json`
-   will be ignored (lest auth information be leaked).
-4. A secure password is generated, and stored securely in `config.local.json`.
-   It is shown to the user once, and they are prompted to take note of it.
-
-The site is then fully configured.
+## 1. Account creation
+
+The user creates the initial account, which triggers the private data setup.
+
+## 2. Data initialization
+
+The user then chooses how to initialize the repo:
+
+* From a `git` repo. The repo is cloned.
+* Empty, meaning a new blank repository is created.
+
+The user is also given the options to control how the server uses SSH keys.
+Allowed options are:
+
+* Generate an SSH key-pair, stored within the private data.
+* Use an existing private key given its path.
+* Use the default SSH identity, which works best if the app is running on an
+  account with existing SSH access.
diff --git a/src/lib/server/data/localConfig.ts b/src/lib/server/data/localConfig.ts
index 2d3ef907..51ef735e 100644
--- a/src/lib/server/data/localConfig.ts
+++ b/src/lib/server/data/localConfig.ts
@@ -53,6 +53,9 @@ export const ConfigLocalJsonStruct = object({
    *
    * The public key file is expected to be the same as the private key, with a
    * `.pub` suffix.
+   *
+   * If this is `null`, then the `ssh` executable will be free to choose an
+   * appropriate SSH key to use.
    */
   keyFile: nullable(string()),
   /** Version of server that last accessed the config.local.json */