From a17240abff067a8b4d9fb9f46944f224c35d0895 Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Tue, 9 Jun 2020 09:48:09 -0400
Subject: [PATCH] some doc tweaks

---
 morph/README.rst | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/morph/README.rst b/morph/README.rst
index 7f8bb655..2fd7dffb 100644
--- a/morph/README.rst
+++ b/morph/README.rst
@@ -3,10 +3,35 @@ Morph
 
 This directory contains Nix-based configuration for the grid.
 This takes the form of Nix expressions in ``.nix`` files
-and some JSON-based configuration in ``.config.json`` files.
+and some JSON-based configuration in ``.json`` files.
 
 This configuration is fed to `morph`_ to make changes to the deployment.
 
+Deploying
+---------
+
+The deployment consists of the public software packages and the private secrets.
+You can deploy these together::
+
+  morph deploy --upload-secrets morph/grid/<testing|production|...>/grid.nix test
+
+Or separately::
+
+  morph deploy morph/grid/<testing|production|...>/grid.nix test
+  morph upload-secrets morph/grid/<testing|production|...>/grid.nix
+
+Separate deployment is useful when the software deploy is done from system which may not be sufficiently secure to host the secrets
+(such as a cloud build machine).
+Secrets should only be hosted on an extremely secure system
+(XXX write the document for what this means).
+
+Note secrets only need to be uploaded after a host in the grid has been rebooted.
+
+See the ``morph`` and ``nixos-rebuild`` documentation for more details about these commands.
+
+Filesystem Layout
+`````````````````
+
 lib
 ---
 
@@ -49,7 +74,7 @@ Each such file contains a minimal Nix expression supplying critical system confi
 These files are referenced by the corresponding ``<hostname>.nix`` files.
 
 Configuring New Storage Nodes
------------------------------
+`````````````````````````````
 
 Storage nodes are brought into the grid in a multi-step process.
 Here are the steps to configure a new node,
-- 
GitLab