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

clean up wording + add missing steps

Browse Source
This commit is contained in:
linnealovespie 2025-01-08 12:32:08 -08:00
parent 313069851c
commit 816c59d7e0
1 changed files with 30 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/operators/tutorial.md
View File

@ -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 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 in and out again of your shell session to get the required permissions for
Docker. Docker.
Alternatively you can run `newgrp` to register the group chnage.
``` ```
# ssh into your server # ssh into your server
@ -53,6 +54,18 @@ docker network create -d overlay proxy
exit 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?" ??? 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! 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. 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?" ??? 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. 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.
@ -131,14 +152,14 @@ It is important to note that `<server-domain>` here is a publicy accessible doma
Yes, this is possible. You need to pass `-D` to `server add` and ensure 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. that your `Host ...` entry in your SSH configuration includes the name.
So, for example: So, for example, in `~/.ssh/config`:
```
Host example.com example Host example.com example
... ...
```
And then: 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. 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 `<app-name>.server.org` or prompt you with a list of servers.
**2. Configure this new `traefix` app** **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 ```bash
abra app config <traefik-domain> abra app config <traefik-domain>
@ -190,7 +211,7 @@ files exist at relevantly named path:
Variables starting with `#` are optional, others are required. Some things to Variables starting with `#` are optional, others are required. Some things to
consider here is that by default our *Traefik* recipe exposes the metric consider here is that by default our *Traefik* recipe exposes the metric
dashboard unauthenticated on the public internet at the URL `<traefik-domain>` dashboard unauthenticated on the public internet at the URL `<traefik-domain>`
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 DASHBOARD_ENABLED=false
@ -198,6 +219,8 @@ DASHBOARD_ENABLED=false
**3. Now it is time to deploy your app:** **3. Now it is time to deploy your app:**
Ensure `<traefic-domain>` is registered in `/etc/hosts` then run:
``` ```
abra app deploy <traefik-domain> abra app deploy <traefik-domain>
``` ```
@ -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. 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` <nextcloud-domain>` is registered in `/etc/hosts`, then we can deploy Nextcloud:
```bash ```bash
abra app deploy <nextcloud-domain> abra app deploy <nextcloud-domain>