From bb29c4688bea2109b828d1cdc805a37ab1826de3 Mon Sep 17 00:00:00 2001
From: 3wc <3wc@doesthisthing.work>
Date: Sat, 3 Jul 2021 23:02:22 +0200
Subject: [PATCH] Add @nikobee's setup/troubleshooting tips

---
 docs/deploy.md          | 36 +++++++++++++++++++++---------------
 docs/troubleshooting.md | 35 +++++++++++++++++++++++++++++++++++
 mkdocs.yml              |  1 +
 3 files changed, 57 insertions(+), 15 deletions(-)
 create mode 100644 docs/troubleshooting.md

diff --git a/docs/deploy.md b/docs/deploy.md
index d37e1fa..b731d8e 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -4,7 +4,9 @@ title: Deploy your first app
 
 In order to deploy an app you need two things:
 
-1. a server (e.g. [Hetzner VPS](https://www.hetzner.com/cloud))
+1. a server (e.g. [Hetzner VPS](https://www.hetzner.com/cloud)), with
+    - SSH access
+    - a public IP address
 2. a DNS provider (e.g. [Gandi](https://www.gandi.net/en))
 
 ## Create your server
@@ -36,6 +38,12 @@ sudo apt-get update
 sudo apt-get install -y docker-ce docker-ce-cli containerd.io
 ```
 
+You'll probably want to add your user to the `docker` group:
+
+```bash
+usermod -a -G docker myusername
+```
+
 ## Bootstrap `abra`
 
 Once your DNS and docker daemon are up, you can install [`abra`](https://git.autonomic.zone/autonomic-cooperative/abra) locally on your developer machine and hook it up to your server.
@@ -72,13 +80,17 @@ abra server add example.com
 
 Where `example.com` is replaced with your server DNS name.
 
-!!! note
+!!! note "About SSH"
+    `abra` uses Docker's built-in SSH support to make a secure connection to a
+    remote Docker daemon, to deploy and manage apps from your local development
+    machine.
 
-    `abra server add` accepts also a `<user>` and `<port>` arguments for your
-    custom SSH connection details. What is happening here is that you are using
-    the underlying SSH machinery to make a secure connection to the server
-    installed Docker daemon. This allows `abra` to run remote deployments from
-    your local development machine.
+    If you need to specify a non-standard port, and/or different username, for SSH,
+    add them as extra arguments:
+
+    ```bash
+    abra server add example.com username 2222
+    ```
 
 Once you've added the sever, you can initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/).
 
@@ -102,7 +114,6 @@ and follow the instructions.
 <node id>
 ```
 
-
 You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance. You can easily share this as a git repository with others.
 
 ## Deploy Traefik
@@ -121,7 +132,7 @@ You will want to take a look at your generated configuration and tweak the `LETS
 abra app traefik config
 ```
 
-This is the required environment variables that you can configure and are injected into the app configuration when deployed.
+Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required.
 
 ```
 abra app traefik deploy
@@ -131,12 +142,7 @@ If you get a message like this:
 ```bash
 ERROR: https://traefik.example.com still isn't up, check status by running "abra app traefik ps"
 ```
-It might need a few seconds more to start up. We can then check that everything came up as expected.
-
-```bash
-abra app traefik ps   # status check
-abra app traefik logs # logs watch
-```
+then it might need a few seconds more to start up. You can run `abra app traefik ps`, as suggested, to see when it's ready – look for `Running` under `CURRENT STATUS` – or `abra app traefik logs` to see app logs.
 
 ## Deploy Nextcloud
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..226fef3
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,35 @@
+---
+title: Troubleshooting
+---
+
+## SSH / connection problems
+
+Assuming:
+- Hostname: `coopcloud.example.com`
+- User: `username`
+- Port: `222`
+
+### Step 1: Can you SSH to the server normally?
+
+Does `ssh username@coopcloud.example.com -p2222` work?
+
+If not, run through your standard oh-no-why-doesn't-SSH-work troubleshooting 🍀.
+
+### Step 2: Can you run remote Docker commands over SSH?
+
+Does `ssh username@coopcloud.example.com -p2222 docker ps` work?
+
+If not:
+- Is the remote Docker daemon running?
+- Is your user in the `docker` group?
+
+### Step 3: Does your Docker context work?
+
+```
+[user@hostname ~]$ DOCKER_CONTEXT=coopcloud.example.com docker ps
+CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
+```
+
+If you get an error message instead:
+- Use `abra server ls` / `docker context ls` to double-check the SSH connection details
+- Try removing the context with `docker context rm coopcloud.example.com`, then re-add it
diff --git a/mkdocs.yml b/mkdocs.yml
index b6d86ba..747f752 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -51,6 +51,7 @@ nav:
       - Roll an app back to a previous version: rollback.md
   - Strategy: strategy.md
   - Roadmap: roadmap.md
+  - Troubleshooting: troubleshooting.md
   - Managed Hosting: managed.md
   - Get in touch: contact.md
   - Acknowledgements: credits.md