Quick start flow on website explains flow better at the start

[izgeri]

Based on this discourse post we'd like to add more context to the quick start flow on conjur.org.

From the post (via @JakeQuilty):

I do agree that for a good chunk of the tutorial running the commands from outside seem weird at first. I just think going back and forth would make the tutorial choppier. Maybe another paragraph explaining why it is the way it is?

In this card we'll define improvements we'd like to make to the quick start flow and validate them, and share them with the web team so that the site can be updated.

[JakeQuilty]

Suggested Changes

• Put at beginning of tutorial:

For the initial set up of the environment, we will be executing our commands in the Docker containers using <code data-lang="shell">docker-compose exec <CONTAINER NAME> <COMMANDS></code>. This enables us to execute commands in multiple containers without leaving our local session. At any point during the tutorial, you may choose to open a shell on the container to run the commands directly. See <a href="https://www.conjur.org/get-started/quick-start/run-demo-app/#step-1">Unit 4: Step 1</a> for an example.

• Edit to Unit 1:Step 4(Verification):
  • The rest of the tutorial uses docker-compose
  • Also, this will display all the containers on the machine and we just want to maker sure our containers for the tutorial are running

docker-compose ps

• Edit to Unit 2:Step 2

  • Conjur generates the following API keys and stores them in a file, my_app_data: should changed for consitency with the rest of the tutorial to:

Conjur generates the following API keys and stores them in a file, <strong>my_app_data</strong>:

• Edit to Unit 4:Step 1:
  • The rest of the tutorial uses docker-compose, so this should be changed for consistency to:

docker-compose exec bot_app bash

• Add to Unit 4:Step 2:
  • I've seen a few people get caught up on this step(including myself) on their first run through.

<strong>Make sure to replace <code><BotApp Api Key></code> with the API key stored in my_app_data.</strong>

Topics for Discussion

• I think the user in this Commons post may have actually been onto something. Every step from Unit 1:Step 5 to Unit 4:Step 1 is executed in the conjur container. It may clean up the command if we just add a step to docker-compose exec conjur bash at the end of Unit 1 and have the user stay in that container until Unit 4. Then just have them switch into the bot_app container then. I'm not sure if this is best practice to keep opening shells in your different containers to run the commands, but we'd be able to take off the docker-compose exec client from most of the commands in the tutorial. I was a little confused by this when I first ran through the tutorial, because I was unfamiliar with Docker.

• In Unit 4 it would be nice if there was an explanation of what is happening when you run program.sh

[alexkalish]

I have an additional change to request. After some research, with @h-artzi's help, we realized that OSS doesn't have a master key. Just a data key. The Quick Start needs to be updated to remove the "master" descriptor from this key name, in the following step:

Essentially, every reference to "master key" or "master data key" need to be replaced with just "data key". Thanks!