Improved SSH instructions

action-ssh.adoc

@@ -26,28 +26,36 @@ actions:
 
 This is a two step process;
 
-1. Setup a volume mount for the `~/.ssh/` directory, that contains a SSH Key.
-2. OliveTin uses the SSH key to connect back to server-with-olivetin or across to server2.
+* [red]#<<ssh-step-1,Step 1>># Give OliveTin a SSH key
+* [red]#<<ssh-step-2,Step 2>># Setup actions that use SSH with this key
 
-Visually, this is what it looks like;
+Visually, this is what it looks like - OliveTin is running in the (orange) container, and then can either connect back to _server-with-olivetin_ or _server2_.
 
 image:images/ssh-diagram.png[]
 
-1. Setup a volume mount for the `~/.ssh/` directory, that contains a SSH Key.
+The steps in detail are below;
 
-.. On `server-with-olivetin`, run `mkdir /opt/OliveTinSshKeys` to create a shared directory for your SSH key file. 
+[#ssh-step-1]
+==== [red]#Step 1#: Give OliveTin a SSH key
+
+Open a terminal window on _server-with-olivetin_. 
+
+[loweralpha]
+. Run `mkdir /opt/OliveTinSshKeys` to create a shared directory for your SSH key file.
 +
 This will later be used as a "volume mount" when you create a docker container. 
 
-. On `server-with-olivetin`, run `ssh-keygen` to generate a SSH key (if you haven't already got one).
+. Run `ssh-keygen` to generate a SSH key just for OliveTin.
 +
+[lowerroman]
 .. Enter the file in which to save the key: `/opt/OliveTinSshKeys/id_rsa`
 .. Enter passphrase (empty for no passphrase): `<enter>`
 +
-This will create a passwordless SSH key that OliveTin can use. It is safe as long as nobody steals your SSH key file!
-+
-You should get something that looks like this. If you get a "permission denied" error when creating files, you could run `chmod 0777 /opt/OliveTinSshKeys` and try again.
+This will create a passwordless SSH key that OliveTin can use. It is safe as long as nobody steals your SSH key file! OliveTin cannot enter passwords into SSH keys, so you have to leave the password blank.
+
+. You should get something that looks like this. If you get a "permission denied" error when creating files, try running `chmod 0777 /opt/OliveTinSshKeys` and try again.
 +
+[source]
 ----
 root@server-with-olivetin: ssh-keygen
 Generating public/private rsa key pair.
@@ -76,18 +84,19 @@ This will create two files, `/opt/OliveTinSshKeys/id_rsa` (your private key) and
 
 . Copy your public key to every server you want to connect to.
 +
-`ssh-copy-id` is a really quick and safe way to do this.
+Using the `ssh-copy-id` command is a really quick and safe way to do this.
 +
 ----
-root@server-with-olivetin: ssh-copy-id root@server-with-olivetin 
+root@server-with-olivetin: ssh-copy-id -i /opt/OliveTinSshKeys/id_rsa.pub root@localhost
 (enter your SSH password)
-root@server2: ssh-copy-id root@server2
+
+root@server2: ssh-copy-id ssh-copy-id -i /opt/OliveTinSshKeys/id_rsa.pub root@server2
 (enter your SSH password)
 ----
 +
 You will be asked to login with a password for each server.
 +
-After you have done that, you will then be able to login with the ssh key instead;
+After you have done that, you will then be able to login with the ssh key instead. Here is a quick way that you can test your SSH key manually;
 +
 ----
 root@server-with-olivetin: ssh -i /opt/OliveTinSshKeys/id_rsa root@server2
@@ -100,14 +109,33 @@ The way to do this is via a "volume mount". When you create the container, you u
 +
 You should mount your SSH keys directory into the OliveTin user's home directory by creating the container like this;
 +
+.If you want to create the container from the command line
 ----
-docker run -v /opt/OliveTinSshKeys/:/home/olivetin/.ssh/ --name OliveTin jamesread/olivetin
+docker run -v /opt/OliveTinSshKeys/:/home/olivetin/.ssh/ -v /etc/OliveTin/:/config --name OliveTin jamesread/olivetin
 ----
 +
+.If you are using docker-compose
+[source,yaml]
+----
+services:
+    olivetin:
+        container_name: olivetin
+        image: jamesread/olivetin
+        volumes:
+          - "/etc/OliveTin/:/config"
+          - "/opt/OliveTinSshKeys:/home/olivetin/.ssh"
+        ports:
+          - "1337:1337"
+        restart: unless-stopped
+----
+
 This also works for things like SSH configuration files, if you want to use them. This is step 1 complete from the diagram above.
-+
-. Thankfully, step 2 is very simple! `ssh` commands in your OliveTin `config.yaml` should work without a password!, and allow OliveTin to access services, files, and other stuff outside of the OliveTin container.
-+
+
+[#ssh-step-2]
+==== [red]#Step 2#: Setup actions that use SSH with this key
+
+Thankfully, step 2 is very simple! `ssh` commands in your OliveTin `config.yaml` should work without a password!, and allow OliveTin to access services, files, and other stuff outside of the OliveTin container.
+
 .OliveTin `config.yaml`
 [source,shell]
 ....

style.css

@@ -84,6 +84,10 @@ h1 {
   vertical-align: middle;
 }
 
+code {
+  background-color: #f7f7f8;
+}
+
 pre {
   background-color: #f7f7f8;
   padding: 1em;
@@ -139,8 +143,21 @@ div.admonitionblock td:first-child {
   padding: 1em;
 }
 
+.red {
+  color: white;
+  border: 1px solid black;
+  padding: .2em;
+  font-weight: bold;
+  background-color: #cc0000;
+}
+
+.red a {
+  color: white;
+}
+
 @media (max-width: 700px) {
   body {
     display: block;
   }
 }
+