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

Small improvements to Operators tutorial

Browse Source 
- Made info boxes collapsible (default: closed)
- Put links at end of sentences for clarity
This commit is contained in:
basebuilder
2024-02-10 16:01:21 +01:00
parent daa594edde
commit fe476b5f76
1 changed files with 23 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/operators/tutorial.md
View File

@ -2,9 +2,7 @@
title: New Operators Tutorial
---
This tutorial assumes you understand the [frequently asked questions](/intro/faq/) as
well as [the moving parts](/intro/strategy/) of the technical problems Co-op
Cloud solves. If yes, proceed :smile:
This tutorial assumes you understand the [frequently asked questions](/intro/faq/) as well as [the moving parts](/intro/strategy/) of the technical problems _Co-op Cloud_ solves. If yes, proceed :smile:
## Deploy your first app
@ -13,11 +11,14 @@ In order to deploy an app you need two things:
1. a server with SSH access and a public IP address
2. a domain name pointing to that server
The tutorial tries to help you make choices about which server and which DNS setup you need to run a Co-op Cloud deployment but it does not go into great depth about how to set up a new server.
This tutorial tries to help you make choices about which server and which DNS setup you need to run a _Co-op Cloud_ deployment but it does not go into great depth about how to set up a new server.
!!! question "Can `abra` help automate this?"
??? question "Can `abra` help automate this?"
`abra` can help bootstrap new servers & configure DNS records for you. We'll skip that for now since we're just getting started. See the [operators handbook](/operators/handbook) for more on these topics after you finish the tutorial.
Our `abra` tool can help bootstrap new servers & configure DNS records for
you. We'll skip that for now since we're just getting started. For more on
these topics after you finish the tutorial see the [operators
handbook](/operators/handbook).
### Server setup
@ -43,7 +44,7 @@ docker swarm init
docker network create -d overlay proxy
```
!!! question "Do you support multiple web proxies?"
??? 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!
@ -58,7 +59,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.
!!! question "How do I know my DNS is working?"
??? 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 <domain>` should show the IP address of your server if things are working.
@ -83,9 +84,9 @@ abra -h # check it works
If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/coop-cloud/abra/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this.
!!! question "Can I install `abra` on my server?"
??? question "Can I install `abra` on my server?"
Yes, this is possible, see [this handbook entry](/operators/handbook/#running-abra-server-side) for more. The instructions for setup are a little different however.
Yes, this is possible. However, the instructions for this setup are different. For more info see [this handbook entry](/operators/handbook/#running-abra-server-side).
#### Add your server
@ -100,21 +101,26 @@ It is important to note that `<domain>` here is a publicy accessible domain name
You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance.
`abra` should now register this server as managed in your server listing:
By now `abra` should have registered this server as managed. To confirm this run:
```
abra server ls
```
!!! warning "Beware of SSH dragons"
??? warning "Beware of SSH dragons :dragon_face:"
`abra` uses plain 'ol SSH under the hood 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.
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/--debug` should help you debug what is going on under the hood. It's best to take a moment to read [this troubleshooting entry](/abra/trouble/#ssh-connection-issues) if you're running into SSH connection issues with `abra`.
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, see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration) for more.
It's possible and quite easy, for more see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration).
### Web proxy setup
@ -154,7 +160,7 @@ abra app new nextcloud -S
The `-S` or `--secrets` flag is used to generate secrets for the app: database connection password, root password and admin password.
!!! warning "Beware of password dragons"
??? warning "Beware of password dragons :dragon:"
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.