From 039bd4257a7a434aa8741a0a72eafddfbe8c8742 Mon Sep 17 00:00:00 2001 From: decentral1se Date: Tue, 25 Jun 2024 16:37:29 +0200 Subject: [PATCH] docs: improve SSH help in operators tutorial --- docs/operators/tutorial.md | 42 +++++++++++++++++++++++++------------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 58bc46c0..c0ab05b7 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -103,14 +103,38 @@ If you run into issues during installation, [please report a ticket](https://git ### Add your server -Now you can connect `abra` with your server. You should have a working SSH configuration before you can do this (e.g. a matching `Host ` entry in `~/.ssh/config` with the correct SSH connection details). That means you can run `ssh ` on your command-line and everything Works :tm:. +Now you can connect `abra` with your server. You must have a working SSH configuration for your server before you can proceed. That means you can run `ssh ` on your command-line and everything Works :tm:. See the [`abra` SSH troubleshooting](/abra/trouble/#ssh-connection-issues) for a working SSH configuration example. + +??? warning "Beware of SSH dragons :dragon_face:" + + Under the hood `abra` uses plain 'ol `ssh` and aims to make use of your + existing SSH configurations in `~/.ssh/config` and interfaces with your + running `ssh-agent` for password protected secret key files. + + Running `server add` with `-d` or `--debug` should help you debug what is + going on under the hood. `ssh -v ...` should also help. If you're running + into SSH connection issues with `abra` take a moment to read [this + troubleshooting entry](/abra/trouble/#ssh-connection-issues). ```bash ssh # make sure it works abra server add ``` -It is important to note that `` here is a publicy accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting. +It is important to note that `` here is a publicy accessible domain name which points to your server IP address. `abra` does make sure this is the case and this is done to avoid issues with HTTPS certificate rate limiting. + +??? warning "Can I use arbitrary server names?" + + 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: + + Host example.com example + ... + + And then: + + 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. @@ -120,20 +144,10 @@ By now `abra` should have registered this server as managed. To confirm this run abra server ls ``` -??? warning "Beware of SSH dragons :dragon_face:" - - Under the hood `abra` uses plain 'ol `ssh` and aims to make use of your - existing SSH configurations in `~/.ssh/config` and interfaces with your - running `ssh-agent` for password protected secret key files. - - Running `server add` with `-d` or `--debug` should help you debug what is going - on under the hood. If you're running into SSH connection issues with `abra` - take a moment to read [this troubleshooting - entry](/abra/trouble/#ssh-connection-issues). - ??? question "How do I share my configs in `~/.abra`?" - It's possible and quite easy, for more see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration). + It's possible and quite easy, for more see [this handbook + entry](/operators/handbook/#understanding-app-and-server-configuration). ### Web proxy setup