From 816c59d7e098dec99e0fdff19c9abfca2507dab7 Mon Sep 17 00:00:00 2001 From: linnealovespie Date: Wed, 8 Jan 2025 12:32:08 -0800 Subject: [PATCH] clean up wording + add missing steps --- docs/operators/tutorial.md | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 9d5ae53..5715d94 100644 --- a/docs/operators/tutorial.md +++ b/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` to register the group chnage. ``` # ssh into your server @@ -53,6 +54,18 @@ docker network create -d overlay proxy exit ``` +If you get an error saying the docker group doesn't exist, then docker didn't create the group during installation. You can create the group manually by running: + +``` + sudo groupadd docker +``` + +Abra can't deploy any applications in future steps if docker cannot run without sudo. To verify docker can run without sudo, run the docker test image: + +``` +docker run hello-world +``` + ??? question "Do you support multiple web proxies?" We do not know if it is feasible and convenient to set things up on an existing server with another web proxy which uses ports `:80` & `:443`. We'd happily receive reports and documentation on how to do this if you manage to set it up! @@ -68,6 +81,14 @@ 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. +On your local machine be sure to add your domain and all relevant subdomains in future steps to your `/etc/hosts` file. For example: + +``` +116.203.211.204 example.com +116.203.211.204 foo.example.com +116.203.211.204 bar.example.com +``` + ??? 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 ` should show the IP address of your server if things are working. @@ -131,14 +152,14 @@ It is important to note that `` here is a publicy accessible doma 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: - + So, for example, in `~/.ssh/config`: + ``` Host example.com example ... - + ``` And then: - abra server add -D example + `abra server add -D example` You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance. @@ -173,7 +194,7 @@ will suggest `.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 @@ -190,7 +211,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 `` -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 @@ -198,6 +219,8 @@ DASHBOARD_ENABLED=false **3. Now it is time to deploy your app:** +Ensure `` is registered in `/etc/hosts` then run: + ``` abra app deploy ``` @@ -219,7 +242,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` ` is registered in `/etc/hosts`, then we can deploy Nextcloud: ```bash abra app deploy