coop-cloud/docs.coopcloud.tech
coop-cloud
/
docs.coopcloud.tech
4
1
Fork 14
Code Issues Pull Requests 2 Releases Activity

Use new golang abra for this guide
continuous-integration/drone/push Build is passing Details 

Closes coop-cloud/organising#149.
This commit is contained in:
decentral1se 2021-09-10 11:39:59 +02:00
parent a0e8d7e7b5
commit 63a0cc9ea4
No known key found for this signature in database
GPG Key ID: 5E2EF5A63E3718CC
2 changed files with 27 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
docs/deploy.md
View File

@ -24,61 +24,25 @@ Where `116.203.211.204` can be replaced with the IP address of your server.
## Install server prerequisites ## Install server prerequisites
You'll want to install [Docker](https://www.docker.com/) both on your server and your local machine. This can be done by following the [install documentation](https://docs.docker.com/engine/install/). You'll want to install [Docker](https://www.docker.com/) on your server. This can be done by following the [install documentation](https://docs.docker.com/engine/install/).
On a [Debian system](https://docs.docker.com/engine/install/debian/), that can be done like so.
```bash
sudo apt-get remove docker docker-engine docker.io containerd runc
sudo apt update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
```
You'll probably want to add your user to the `docker` group:
```bash
usermod -a -G docker myusername
```
## Bootstrap `abra` ## Bootstrap `abra`
!!! danger "Here be dragons I" Once your DNS and docker daemon are up, you can install [`abra`](https://git.coopcloud.tech/coop-cloud/abra) locally on your developer machine and hook it up to your server.
`abra` is an officially deprecated tool as of August 1rst 2021 but it is
still our main daily driver to managing Co-op Cloud instances. We're in the
middle of a [Golang](https://golang.org) port which you can learn more about
it [this blog post](https://coopcloud.tech/blog/this-month-in-coop-cloud-july/).
There will only be bug and security fixes provided for `abra` from now on, please
feel free to raise issues when you run into them.
Once your DNS and docker daemon are up, you can install [`abra`](https://git.autonomic.zone/autonomic-cooperative/abra) locally on your developer machine and hook it up to your server.
Firstly, install `abra` locally. Firstly, install `abra` locally.
!!! danger "Here be dragons II"
`abra` is written in Bash version 4 and if you have a version older than
that, you will face issues. You can check your current bash version by
running `bash --version`. Some developers of the tool are using Zsh > 5 and
things work fine. Some MacOS users have had to use this [Homebrew
formula](https://formulae.brew.sh/formula/bash#default) to upgrade their
Bash.
```bash ```bash
curl https://install.abra.autonomic.zone | bash curl https://install.abra.autonomic.zone | bash
``` ```
The source for this script [is here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/deploy/install.abra.coopcloud.tech/installer). The source for this script [is here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer).
You may need to add the `~/.local/bin/` directory with your `$PATH` in order to run the executable. You may need to add the `~/.local/bin/` directory with your `$PATH` in order to run the executable.
```bash ```bash
export PATH=$PATH:$HOME/.local/bin export PATH=$PATH:$HOME/.local/bin
abra --help # check it works abra -h # check it works
``` ```
Now you can connect `abra` with your new server. Now you can connect `abra` with your new server.
@ -90,39 +54,24 @@ abra server add example.com
Where `example.com` is replaced with your server DNS name. Where `example.com` is replaced with your server DNS name.
!!! note "About SSH" !!! note "About SSH"
`abra` uses Docker's built-in SSH support to make a secure connection to a
remote Docker daemon, to deploy and manage apps from your local development
machine.
If you need to specify a non-standard port, and/or different username, for SSH, `abra` uses Docker's built-in SSH support to make a secure connection to a
add them as extra arguments: remote Docker daemon, to deploy and manage apps from your local development
machine.
```bash If you need to specify a non-standard port, and/or different username, for SSH,
abra server add example.com username 2222 add them as extra arguments:
```
Once you've added the sever, you can initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/). ```bash
abra server add example.com username 2222
```
Once you've added the sever, you can initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/) on your server.
```bash ```bash
abra server example.com init abra server example.com init
``` ```
You might see some messages from docker-swarm such as:
```bash
Swarm initialized: current node (<node id>) is now a
manager.
To add a worker to this swarm, run the following command:
docker swarm join --token <token> <IP address>
To add a manager to this swarm, run 'docker swarm join-token manager'
and follow the instructions.
<node id>
```
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 can easily share this as a git repository with others. 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 can easily share this as a git repository with others.
## Deploy Traefik ## Deploy Traefik
@ -130,31 +79,21 @@ You will now have a new `~/.abra/` folder on your local file system which stores
In order to have your Co-op cloud installation automagically provision SSL certificates, we will first install [Traefik](https://doc.traefik.io/traefik/). This tool 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. In order to have your Co-op cloud installation automagically provision SSL certificates, we will first install [Traefik](https://doc.traefik.io/traefik/). This tool 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.
```bash ```bash
abra app new --server example.com --domain traefik.example.com traefik abra app new traefik
``` ```
We can then choose `traefik` as the app name.
You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value: You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value:
```bash ```bash
abra app traefik config abra app config traefik
``` ```
Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required. Every app you deploy will have one of these `.env` files, which contains variables which will be injected into app configurations when deployed. Variables starting with `#` are optional, others are required.
``` ```
abra app traefik deploy abra app deploy traefik
``` ```
If you get a message like this:
```bash
ERROR: https://traefik.example.com still isn't up, check status by running "abra app traefik ps"
```
then it might need a few seconds more to start up. You can run `abra app traefik ps`, as suggested, to see when it's ready – look for `Running` under `CURRENT STATUS` – or `abra app traefik logs` to see app logs.
## Deploy Nextcloud ## Deploy Nextcloud
And now we can deploy apps. And now we can deploy apps.
@ -162,43 +101,33 @@ And now we can deploy apps.
Let's create a new Nextcloud app. Let's create a new Nextcloud app.
```bash ```bash
abra app new --server example.com --domain cloud.example.com nextcloud abra app new nextcloud
``` ```
We can then choose `nextcloud` as the app name.
And we need to generate secrets for the app: database connection password, root password and admin password. And we need to generate secrets for the app: database connection password, root password and admin password.
```bash ```bash
abra app nextcloud secret generate --all abra app secret generate --all nextcloud
``` ```
If abra complains about lacking pwqgen, it is available in the packet passwdqc on debian. Install it with
```bash
sudo apt-get install passwdqc
```
and run the previous command again.
!!! warning !!! warning
Take care, these secrets are only shown once on the terminal so make sure 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 to take note of them! `abra` makes use of the [Docker secrets](/secrets/)
secrets](https://docs.docker.com/engine/swarm/secrets/) mechanism to ship mechanism to ship these secrets securely to the server and store them as
these secrets securely to the server and store them as encrypted data. encrypted data.
Then we can deploy the Nextcloud. Then we can deploy the Nextcloud.
```bash ```bash
abra app nextcloud deploy abra app deploy nextcloud
``` ```
And once again, we can watch to see that things come up correctly. We can watch to see that things come up correctly.
```bash ```bash
abra app nextcloud ps # status check abra app ps nextcloud # status check
abra app nextcloud logs # logs watch abra app logs nextcloud # logs watch
``` ```
!!! note !!! note
@ -207,7 +136,7 @@ abra app nextcloud logs # logs watch
command under `watch` like so. command under `watch` like so.
```bash ```bash
watch abra app nextcloud ps watch abra app ps nextcloud
``` ```
And you can wait until you see that all containers have the "Running" state. And you can wait until you see that all containers have the "Running" state.

9
docs/overview.md
View File

@ -51,15 +51,6 @@ Learn more about why we use Docker swarm [in the FAQ section](/faq/#why-docker-s
## Command-line tool ## Command-line tool
!!! danger "Here be dragons"
`abra` is an officially deprecated tool as of August 1rst 2021 but it is
still our main daily driver to managing Co-op Cloud instances. We're in the
middle of a [Golang](https://golang.org) port which you can learn more about
it [this blog post](https://coopcloud.tech/blog/this-month-in-coop-cloud-july/).
There will only be bug and security fixes provided for `abra` from now on, please
feel free to raise issues when you run into them. More Coming Soon :tm:
Finally, with an application and an application environment, we need a tool to read that package format and actually deploy it to the environment. For this, we have developed and published the [abra] command-line tool. Finally, with an application and an application environment, we need a tool to read that package format and actually deploy it to the environment. For this, we have developed and published the [abra] command-line tool.
Abra aims at providing a simple command-line interface for managing your own co-op cloud. You can bootstrap machines with the required tools, create new applications, deploy them, back them up, restore them and so on. Abra aims at providing a simple command-line interface for managing your own co-op cloud. You can bootstrap machines with the required tools, create new applications, deploy them, back them up, restore them and so on.