toolshed/docs.coopcloud.tech
3
1
Fork 21
Code Issues 8 Pull Requests Packages Releases Activity

docs: improve SSH help in operators tutorial
All checks were successful
continuous-integration/drone/push Build is passing
Details

Browse Source
This commit is contained in:
decentral1se
2024-06-25 16:37:29 +02:00
parent 1a9d255b2f
commit 039bd4257a
1 changed files with 28 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/operators/tutorial.md
View File

@ -103,14 +103,38 @@ If you run into issues during installation, [please report a ticket](https://git
### Add your server ### 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 <server-domain>` entry in `~/.ssh/config` with the correct SSH connection details). That means you can run `ssh <server-domain>` 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 <server-domain>` 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 ```bash
ssh <server-domain> # make sure it works ssh <server-domain> # make sure it works
abra server add <server-domain> abra server add <server-domain>
``` ```
It is important to note that `<domain>` 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 `<server-domain>` 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. 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 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`?" ??? 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 ### Web proxy setup