propellor spin

1 files changed, 19 insertions, 10 deletions

diff --git a/README b/README
index c46131b8..ce9769c0 100644
--- a/README
+++ b/README
@@ -6,10 +6,13 @@ properties, taking action as necessary when a property is not yet met.
 
 The design is intentionally very minimal.
 
-Propellor lives in a git repository, and so to set it up it's cloned
-to a system, and "make" can be used to pull down any new changes,
-and compile and run propellor. This can be done by a cron job, or
-a local propellor on your laptop can ssh in and run it.
+Propellor lives in a git repository. You'll typically want to have
+the repository checked out on a laptop, in order to make changes and push
+them out to hosts. Each host will also have a clone of the repository,
+and in that clone "make" can be used to build and run propellor.
+This can be done by a cron job (which propellor can set up),
+or a remote host can be triggered to update by running propellor
+on your laptop: propellor --spin $host
 
 Properties are defined using Haskell. Edit config.hs to get started.
 
@@ -26,9 +29,15 @@ and so it's easy to factor out things like classes of hosts as desired.
 ## bootstrapping and private data
 
 To bootstrap propellor on a new host, use: propellor --spin $host
-This looks up the git repository's remote.origin.url (or remote.deploy.url
-if available) and logs into the host, clones the url (if not already
-done), and sets up and runs propellor in /usr/local/propellor
+
+That clones the local git repository to the remote host (securely over ssh
+and without needing any central server!), if it doesn't already have
+a clone.
+
+The repository on the remote host will have its origin set to the local git
+repository's remote.origin.url (or remote.deploy.url if available).
+This way, when propellor is run on the remote host, it can contact
+whatever central git repository you're using.
 
 Private data such as passwords, ssh private keys, etc should not be checked
 into a propellor git repository in the clear, unless you want to restrict
@@ -43,10 +52,10 @@ for available fields.
 
 ## using git://... securely
 
-It's often easiest to deploy propellor to a host by cloning a git:// or
-http:// repository rather than by cloning over ssh://. To avoid a MITM
+It's often easiest for a remote host to use a git:// or http://
+url to its origin repository, rather than ssh://. So, to avoid a MITM
 attack, propellor checks that the top commit in the git repository is gpg
-signed by a trusted gpg key, and refuses to deploy it otherwise. 
+signed by a trusted gpg key, and refuses to deploy it otherwise.
 
 This is only done when privdata/keyring.gpg exists. To set it up: