diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 1923ed5..dcfd01c 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`](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 # 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 @@ -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 ` should show the IP address of your server if things are working. @@ -129,12 +142,13 @@ It is important to note that `` 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 `.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 @@ -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 `` -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 `` is registered in `/etc/hosts` then run: + ``` abra app deploy ``` @@ -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` ` is registered in `/etc/hosts`, then we can deploy Nextcloud: ```bash abra app deploy