patcon/docs.coopcloud.tech
0
0
Fork 0
forked from coop-cloud/docs.coopcloud.tech
Code Issues Pull Requests Projects Releases Wiki Activity

Use new golang abra for this guide

Browse Source 
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
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/).
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
```
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/).
## Bootstrap `abra`
!!! danger "Here be dragons I"
`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.
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.
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
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.
```bash
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.
@ -90,39 +54,24 @@ abra server add example.com
Where `example.com` is replaced with your server DNS name.
!!! 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,
add them as extra arguments:
`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.
```bash
abra server add example.com username 2222
```
If you need to specify a non-standard port, and/or different username, for SSH,
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
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.
## 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.
```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:
```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.
```
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
And now we can deploy apps.
@ -162,43 +101,33 @@ And now we can deploy apps.
Let's create a new Nextcloud app.
```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.
```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
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](https://docs.docker.com/engine/swarm/secrets/) mechanism to ship
these secrets securely to the server and store them as encrypted data.
to take note of them! `abra` makes use of the [Docker secrets](/secrets/)
mechanism to ship these secrets securely to the server and store them as
encrypted data.
Then we can deploy the Nextcloud.
```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
abra app nextcloud ps # status check
abra app nextcloud logs # logs watch
abra app ps nextcloud # status check
abra app logs nextcloud # logs watch
```
!!! note
@ -207,7 +136,7 @@ abra app nextcloud logs # logs watch
command under `watch` like so.
```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.

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
!!! 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.
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.