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

Improve operators tutorial, mention cloud-init

Browse Source
This commit is contained in:
cyrnel
2025-09-15 12:58:38 -04:00
parent 69564fdadf
commit a56861701c
1 changed files with 40 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/operators/tutorial.md
View File

@ -13,24 +13,23 @@ In order to deploy an app you need two things:
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.
### Server setup
We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html).
Co-op Cloud has itself near zero system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
### Server provisioning
We will deploy a new Nextcloud instance in this guide, so you will only need 1GB of RAM according to [their documentation](https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html). You may also be interested in this [FAQ entry](/intro/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.
Co-op Cloud is designed to run on a variety of hardware, so you can use those single-board computers, old laptops/desktops, or refurbished servers. However, hardware setup is a skill that's beyond the scope of this guide. As long as it's running Linux and has networking, it should be fine! Most Co-op Cloud deployments have been run on Debian machines so far.
Most Co-op Cloud deployments have been run on Debian machines so far. Some experiments have been done on single board computers & servers with low resource capacities.
If you don't have the time or equipment to run your own hardware, rented hardware is fine too! There are many hosting providers which will provide a Linux server to you for a monthly fee.
You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy ([Traefik](https://traefik.io)) keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.
### Server configuration
`abra` has support for creating servers (`abra server new`) but that is a more advanced automation feature which is covered in the [handbook](/operators/handbook). For this tutorial, we'll focus on the basics. Assuming you've managed to create a testing VPS with some `$hosting_provider`, you'll need to install Docker, add your user to the Docker group & setup swarm mode:
Assuming you've got a running server, it's now time to configure it.
!!! warning "You may need to log in/out"
Co-op Cloud has very few system requirements. You only need to worry about the system resource usage of your apps and the overhead of running containers with the docker runtime (often negligible. If you want to know more, see [this FAQ entry](/intro/faq/#isnt-running-everything-in-containers-inefficient)).
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.
To get started, you'll need to install Docker, add your user to the Docker group & setup swarm mode. Many hosting providers support [cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html), which allows you to automate the steps in this section. If that applies to you, you can use [our cloud-init file](https://git.coopcloud.tech/toolshed/abra/raw/branch/main/scripts/cloud-init/cloud-init.yaml).
Otherwise, here are the step required:
```
# ssh into your server
@ -39,34 +38,31 @@ ssh <server-domain>
# docker install convenience script
wget -O- https://get.docker.com | bash
# check that docker was installed correctly
sudo docker run hello-world
# now setup swarm
sudo docker swarm init
sudo docker network create -d overlay proxy
```
#### Using docker without sudo
Abra can't deploy any applications in future steps unless it can run `docker` commands without sudo.
```
# check if the docker group exists
groups | grep docker
# if the docker group doesn't already exist, add it manually
sudo groupadd docker
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 <server-domain>
# back on the server, setup swarm
docker swarm init
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.
After running `usermod`, you may need to (depending on your system) log out (`exit`) and back in again (`ssh <server-domain>`) to get the required permissions for Docker before proceeding.
??? 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!
The [official Docker documentation](https://docs.docker.com/engine/install/linux-postinstall/) can help if you run into further issues.
### DNS setup
@ -79,7 +75,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.
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.
Warning: If the you are in the same local network 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?"
@ -140,11 +136,11 @@ Now you can connect `abra` with your server. You must have a working SSH configu
troubleshooting entry](/abra/trouble/#ssh-connection-issues).
```bash
ssh <server-domain> # make sure it works
ssh <server-domain> hostname -I # make sure it works
abra server add <server-domain>
```
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.
It is important to note that `<server-domain>` here is a publicly 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?"
@ -180,6 +176,12 @@ Traefik is the main entrypoint for all web requests (e.g. like NGINX) and
supports automatic SSL certificate configuration and other quality-of-life
features which make deploying libre apps more enjoyable.
You need to keep port `:80` and `:443` free on your server for web proxying to your apps. Typically, you don't need to keep any other ports free as the core web proxy keeps all app ports internal to its network. Sometimes however, you need to expose an app port when you need to use a transport which would perform better or more reliably without proxying.
??? 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!
**1. To get started, you'll need to create a new app:**
```bash
@ -189,6 +191,8 @@ abra app new traefik
Choose your newly registered server and specify a domain name. By default `abra`
will suggest `<app-name>.server.org` or prompt you with a list of servers.
??? question "Should I use www.server.org for traefik?"
Generally no. No one will be directly accessing the traefik domain name unless they want to see the traefik dashboard. You should reserve the `www` or apex domains for apps like [custom-html](https://recipes.coopcloud.tech/custom-html-tiny) which let you host sites. Traefik is just a proxy to other apps!
**2. Configure this new `traefix` app**
@ -217,8 +221,6 @@ DASHBOARD_ENABLED=false
**3. Now it is time to deploy your app:**
Ensure `<traefic-domain>` is registered in `/etc/hosts` then run:
```
abra app deploy <traefik-domain>
```
@ -231,7 +233,7 @@ Voila. Abracadabra :magic_wand: your first app is deployed :sparkles:
And now we can deploy apps. Let's create a new Nextcloud app.
```bash
abra app new nextcloud -S
abra app new nextcloud --secrets
```
The `-S` or `--secrets` flag is used to generate secrets for the app: database connection password, root password and admin password.
@ -240,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.
Make sure` <nextcloud-domain>` is registered in `/etc/hosts`, then we can deploy Nextcloud:
Now we can deploy Nextcloud:
```bash
abra app deploy <nextcloud-domain>
@ -254,7 +256,7 @@ abra app logs <nextcloud-domain> # logs trailing
abra app errors -w <nextcloud-domain> # error catcher
```
Your new `traefik` instance will detect that a new app is coming up and generate SSL certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<netcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
Your new `traefik` instance will detect that a new app is coming up and generate TLS certificates for it. You can see what `traefik` is up to using the same commands above but replacing `<nextcloud-domain>` with the `<traefik-domain>` you chose earlier (`abra app ls` will remind you what domains you chose :grinning:).
### Upgrade Nextcloud