docs/operators/tutorial.md

@@ -30,6 +30,7 @@ You need to keep port `:80` and `:443` free on your server for web proxying to y
     When running `usermod ...`, you may need to (depending on your system) log
     in and out again of your shell session to get the required permissions for
     Docker.
+    Alternatively you can run [`newgrp`](https://www.man7.org/linux/man-pages/man1/newgrp.1.html) to register the group chnage.
 
 ```
 # ssh into your server
@@ -38,9 +39,18 @@ ssh <server-domain>
 # docker install convenience script
 wget -O- https://get.docker.com | bash
 
+# check if the docker group exists
+groups | grep docker
+
+# if the docker group doesn't already exist, add it manually
+sudo groupadd docker
+
 # add user to docker group
 sudo usermod -aG docker $USER
 
+# check that docker installed correctly
+docker run hello-world
+
 # exit and re-login to load the group
 exit
 ssh <server-domain>
@@ -52,6 +62,7 @@ docker network create -d overlay proxy
 # now you can exit and start using abra
 exit
 ```
+Abra can't deploy any applications in future steps if the docker group cannot run without sudo. If you install docker a different way, it may not create a docker group automatically. The [official Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/) can help if you run into further issues. 
 
 ??? question "Do you support multiple web proxies?"
 
@@ -68,6 +79,8 @@ Your entries in your DNS provider setup might look like the following.
 
 Where `116.203.211.204` can be replaced with the IP address of your server.
 
+Warning: If the you are in the same local netwrok as the server, you might run into [NAT Hairpin](https://superuser.com/questions/663820/port-forwarding-from-inner-network-to-inner-network-hairpin-nat) issues.
+
 ??? question "How do I know my DNS is working?"
 
     You can use a tool like `dig` on the command-line to check if your server has the necessary DNS records set up. Something like `dig +short <domain>` should show the IP address of your server if things are working.
@@ -129,12 +142,13 @@ It is important to note that `<server-domain>` here is a publicy accessible doma
 
 ??? warning "Can I use arbitrary server names?"
 
-    Yes, this is possible. Snsure that your `Host ...` entry in your SSH
-    configuration includes the name. So, for example:
-
+    Yes, this is possible. You need to pass `-D` to `server add` and ensure
+    that your `Host ...` entry in your SSH configuration includes the name.
+    So, for example, in `~/.ssh/config`:
+    ```
       Host example.com example
         ...
-
+    ```
     And then:
 
       abra server add example
@@ -172,7 +186,7 @@ will suggest `<app-name>.server.org` or prompt you with a list of servers.
 
 **2. Configure this new `traefix` app**
 
-You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value. You can do that by running `abra app config`:
+You will want to take a look at your generated configuration and update the placeholder `LETS_ENCRYPT_EMAIL` value, used by Let's Encrypt to manage SSL certificates. You can do that by running `abra app config`:
 
 ```bash
 abra app config <traefik-domain>
@@ -189,7 +203,7 @@ files exist at relevantly named path:
 Variables starting with `#` are optional, others are required. Some things to
 consider here is that by default our *Traefik* recipe exposes the metric
 dashboard unauthenticated on the public internet at the URL `<traefik-domain>`
-it is deployed to, which is not ideal. You can disable this with:
+it is deployed to, which while helpful for debugging, is not ideal in production environments. You can disable this with:
 
 ```
 DASHBOARD_ENABLED=false
@@ -197,6 +211,8 @@ DASHBOARD_ENABLED=false
 
 **3. Now it is time to deploy your app:**
 
+Ensure `<traefic-domain>` is registered in `/etc/hosts` then run: 
+
 ```
 abra app deploy <traefik-domain>
 ```
@@ -218,7 +234,7 @@ The `-S` or `--secrets` flag is used to generate secrets for the app: database c
 
     Take care, these secrets are only shown once on the terminal so make sure to take note of them! `abra` makes use of the [Docker secrets](/operators/handbook/#managing-secret-data) mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in `/run/secrets` on the container file system.
 
-Then we can deploy Nextcloud:
+Make sure` <nextcloud-domain>` is registered in `/etc/hosts`, then we can deploy Nextcloud:
 
 ```bash
 abra app deploy <nextcloud-domain>