From 816c59d7e098dec99e0fdff19c9abfca2507dab7 Mon Sep 17 00:00:00 2001 From: linnealovespie Date: Wed, 8 Jan 2025 12:32:08 -0800 Subject: [PATCH 1/3] 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 From dc2c84c84944778c9d79947f368fc7fb0b9f2e6f Mon Sep 17 00:00:00 2001 From: linnealovespie Date: Tue, 28 Jan 2025 21:57:21 -0800 Subject: [PATCH 2/3] commens --- docs/operators/tutorial.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 5715d94..7ec1641 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -30,7 +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. + 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 @@ -39,9 +39,18 @@ ssh # 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 @@ -53,18 +62,7 @@ docker network create -d overlay proxy # now you can exit and start using abra 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 -``` +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?" @@ -159,7 +157,7 @@ It is important to note that `` here is a publicy accessible doma ``` And then: - `abra server add -D example` + `abra server add 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. From 6302d7015c467570bcb7a8286e92e96909e49041 Mon Sep 17 00:00:00 2001 From: Ammar Hussein Date: Sun, 11 May 2025 21:37:57 -0700 Subject: [PATCH 3/3] add a note on the hairpin issue --- docs/operators/tutorial.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 87c0c96..dcfd01c 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -79,13 +79,7 @@ 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 -``` +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?"