From 0375f9bf9643c472fc3d101ae9f99319877f926e Mon Sep 17 00:00:00 2001
From: Solomon Hykes <solomon@dagger.io>
Date: Wed, 16 Jun 2021 16:50:38 +0000
Subject: [PATCH] Docs: 101: explain key import, group setup steps

Signed-off-by: Solomon Hykes <solomon@dagger.io>
---
 docs/learn/101-use.md | 55 ++++++++++++++++++++++++++-----------------
 1 file changed, 34 insertions(+), 21 deletions(-)

diff --git a/docs/learn/101-use.md b/docs/learn/101-use.md
index 1384ceec..5ba05a4b 100644
--- a/docs/learn/101-use.md
+++ b/docs/learn/101-use.md
@@ -14,51 +14,64 @@ This will allow you to deploy something "real" right away, without having to con
 In later guides, you will learn how to configure Dagger to deploy to your own infrastructure. And, for advanced users,
 how to share access to your infrastructure in the same way that we are sharing access to ours now.
 
-## Before we start
+## Initial setup
 
-First, you'll need to make sure [you have installed dagger on your local machine](/install).
+### Install Dagger
 
-## Let's deploy our first application
+First, make sure [you have installed dagger on your local machine](/install).
 
-**Step 1**: Clone the example repository
+### Setup example app
+
+You will need a local copy of the [Dagger examples repository](https://github.com/dagger/examples).
+NOTE: you may use the same local copy across all tutorials.
 
 ```shell
-git clone https://github.com/dagger/examples.git
+git clone https://github.com/dagger/examples
 ```
 
-**Step 2**: Go the todoapp directory
-
-`todoapp` is a simple Todo-list application written in Javascript using React.
-
-Go to the app directory:
+Make sure that all commands are run from the `todoapp` directory:
 
 ```shell
-cd ./examples/todoapp
+cd examples/todoapp
 ```
 
-**Step 3**: Decrypt the inputs
+### Import the tutorial key
 
-The example app contains encrypted secrets and other pre-configured inputs, here is how to decrypt them:
+Dagger natively supports encrypted secrets: when a user inputs a value marked as secret
+(for example a password, API token or ssh key) it is automatically encrypted with that user's key,
+and no other user can access that value unless they are explicitly given access.
 
-```sh
+In the interest of security, Dagger has no way *not* to encrypt a secret value.
+But this causes a dilemma for this tutorial: how do we give unrestricted public access to our
+(carefully sandboxed) infrastructure, so that anyone can deploy to it?
+
+To solve this dilemma, we included the private key used to encrypt the tutorial's secret inputs.
+Simply import the key to your Dagger installation, and you're good to go:
+
+```shell
 dagger input list || curl -sfL https://releases.dagger.io/examples/key.txt >> ~/.config/dagger/keys.txt
 ```
 
-**Step 4**: Deploy!
+## First deployment
+
+Now that your environment is setup, you are ready to deploy:
 
 ```shell
 dagger up
 ```
 
-At the end of the deploy, you should see a list of outputs. There is one that is named `url`. This is the URL where our app has been deployed. If you go to this URL, you should see your application live!
+That's it! You have just made your first deployment with Dagger.
 
-## Change some code and re-deploy
+The URL of your newly deployed app should be visible towards the end of the command output.
+If you visit that URL, you should see your application live!
 
-This repository is already configured to deploy the code in the directory `./todoapp`, so you can change some code (or replace the app code with another react app!) and re-run the following command to re-deploy when you want your changes to be live:
+## Code, deploy, repeat
 
-```shell
-dagger up
-```
+This environment is pre-configured to deploy from the `./todoapp` directory,
+so you can make any change you want to that directory, then deploy it with `dagger up`.
+You can even replace our example React code with any React application!
+
+NOTE: you don't have to commit your changes to the git repository before deploying them.
 
 ## Under the hood