kawaiipunk/docs.coopcloud.tech
0
0
Fork 0
forked from toolshed/docs.coopcloud.tech
Code Pull Requests Activity

archiving, laying out menu

Browse Source
This commit is contained in:
cellarspoon
2022-01-21 13:26:58 +01:00
parent 53beb09910
commit 6adbf771d2
31 changed files with 42 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/x-archive/abra.md Normal file
View File

@ -0,0 +1,34 @@
---
title: Abra
---
## Enable auto-completion
### Bash
Copy `scripts/autocomplete/bash` into `/etc/bash_completion.d/` and rename
it to abra.
```
sudo cp scripts/autocomplete/bash /etc/bash_completion.d/abra
source /etc/bash_completion.d/abra
```
In development, you can source the script in your git checkout, just make sure
to set `PROG=abra`, otherwise it'll add completion to the wrong command:
```
PROG=abra source /path/to/abra/scripts/autocomplete/bash
```
### (Fi)Zsh
(fi)zsh doesn't have an autocompletion folder by default but you can create one, then copy `scripts/autocomplete/zsh` into it and add a couple lines to your `~/.zshrc` or `~/.fizsh/.fizshrc`
```
sudo mkdir /etc/zsh/completion.d/
sudo cp scripts/autocomplete/zsh /etc/zsh/completion.d/abra
echo "PROG=abra\n_CLI_ZSH_AUTOCOMPLETE_HACK=1\nsource /etc/zsh/completion.d/abra" >> ~/.zshrc
```
(replace .zshrc with ~/.fizsh/.fizshrc if you use fizsh)

15
docs/x-archive/app-config-guide.md Normal file
View File

@ -0,0 +1,15 @@
---
title: App config guide
---
The tips that were previously on this page have moved to the relevant recipe README files, to keep everything in one place while we figure out the best long-term home for per-app documentation. Find the READMEs here:
- [Keycloak][keycloak]
- [Nextcloud][nextcloud]
- [Drone][drone]
- [Peertube][peertube]
[keycloak]: https://git.coopcloud.tech/coop-cloud/keycloak
[nextcloud]: https://git.coopcloud.tech/coop-cloud/nextcloud
[drone]: https://git.coopcloud.tech/coop-cloud/drone
[peertube]: https://git.coopcloud.tech/coop-cloud/peertube

145
docs/x-archive/apps.md Normal file
View File

@ -0,0 +1,145 @@
---
title: Application catalogue
---
<!-- DO NOT EDIT TABLES MANUALLY
App information is auto-generated with abra/app-catalogue.sh:
https://git.autonomic.zone/coop-cloud/abra/src/branch/main/app-catalogue.sh
Manual edits will be over-written the next time that script is run.
-->
An experimental version of this catalogue is available here:
https://dev.apps.coopcloud.tech
## Applications
| **Name** | **Status** | **Image** | **Healtcheck** | **Backups** | **Email** | **CI** | **Single-Sign-On** |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [Adapt Authoring Tool](https://git.autonomic.zone/coop-cloud/adapt_authoring) | ❸🍎 | ❹💣 | ✅ | ❌ | ❌ | ❷💛 | ❌ |
| [alerta](https://git.autonomic.zone/coop-cloud/alerta) | | 0 | | | | | |
| [botamusique](https://git.autonomic.zone/coop-cloud/botamusique) | | | | | | | |
| [calendso](https://git.autonomic.zone/coop-cloud/calendso) | | 4 | ❌ | ❌ | ✅ | ❌ | ⛔ |
| [capsul](https://git.autonomic.zone/coop-cloud/capsul) | ❸🍎 | ❹💣 | ✅ | ❌ | ❶💚 | ❷💛 | ❌ |
| [CiviCRM-Backdrop](https://git.autonomic.zone/coop-cloud/civicrm-backdrop) | ❹💣 | ? | ❌ | ❌ | ❌ | ❌ | ❌ |
| [collabora](https://git.autonomic.zone/coop-cloud/collabora) | ❶💚 | ❶💚 | ❌ | ❌ | ❶💚 | ❷💛 | ❌ |
| [cryptpad](https://git.autonomic.zone/coop-cloud/cryptpad) | | | | | | | |
| [Custom HTML](https://git.autonomic.zone/coop-cloud/custom-html) | ❷💛 | ❶💚 | ❌ | ❌ | ⛔ | ❷💛 | ❌ |
| [Discourse](https://git.autonomic.zone/coop-cloud/discourse) | | [`bitnami/discourse`](https://hub.docker.com/r/bitname/discourse) | yes | no | yes | no | no |
| [Drone](https://git.autonomic.zone/coop-cloud/drone) | 1, alpha | ❶💚 | ✅ | ? | ? | ❷💛 | ❶💚 (OAuth) |
| [Federated Wiki](https://git.autonomic.zone/coop-cloud/federatedwiki) | ❹💣 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [Filerun](https://git.autonomic.zone/coop-cloud/filerun) | 0, work-in-progress | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [Filestash](https://git.autonomic.zone/coop-cloud/filestash) | ❹💣 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [foodsoft](https://git.autonomic.zone/coop-cloud/foodsoft) | | 4 | | | | | |
| [ghost](https://git.autonomic.zone/coop-cloud/ghost) | | | | | | | |
| [Gitea](https://git.autonomic.zone/coop-cloud/gitea) | ❶💚 | ❶💚 | ✅ | ✅ | ? | ❷💛 | (OAuth) |
| [H5ai](https://git.autonomic.zone/coop-cloud/h5ai) | ❸🍎 | ❸🍎 | ✅ | ❌ | ⛔ | ❌ | ❌ |
| [Hedgedoc](https://git.autonomic.zone/coop-cloud/hedgedoc) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❶💚 (OAuth) |
| [Hometown](https://git.autonomic.zone/coop-cloud/hometown) | | [`decentral1se/hometown`](https://hub.docker.com/r/decentral1se/hometown) | | | | | |
| [Invoiceninja](https://git.autonomic.zone/coop-cloud/invoiceninja) | ❹💣 | ❸🍎 | ❌ | ❌ | ? | ❌ | ? |
| [Jupyter Lab](https://git.autonomic.zone/coop-cloud/jupyter-lab) | 1 | `jupyter/datascience-notebook` | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [keycloak](https://git.autonomic.zone/coop-cloud/keycloak) | ❷💛 | ❶💚 | ✅ | ? | ❸🍎 | ❷💛 | ⛔ |
| [Keyoxide](https://git.autonomic.zone/coop-cloud/keyoxide) | ❷💛 | ❶💚 | ✅ | ❌ | ⛔ | ❷💛 | ⛔ |
| [Kimai](https://git.autonomic.zone/coop-cloud/kimai) | ? | ❷💛 | ❌ | ❌ | ❌ | ❷💛 | ❌ |
| [Kutt](https://git.autonomic.zone/coop-cloud/kutt) | ❸🍎 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [laplace](https://git.autonomic.zone/coop-cloud/laplace) | | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [levelfly](https://git.autonomic.zone/coop-cloud/levelfly) | | 4 | | | | | |
| [Loomio](https://git.autonomic.zone/coop-cloud/loomio) | ❹💣 | [`loomio/*`](https://hub.docker.com/r/loomio) | ❌ | ❌ | ? | ❌ | ❌ |
| [mailman3](https://git.autonomic.zone/coop-cloud/mailman3) | 1, alpha | [`maxking/mailman-*`](https://github.com/maxking/docker-mailman) | | | | | |
| [Mailu](https://git.autonomic.zone/coop-cloud/mailu) | ❸🍎 | ❶💚 | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [Mastodon](https://git.autonomic.zone/coop-cloud/mastodon) | | [`tootsuite/mastodon`](https://hub.docker.com/r/tootsuite/mastodon) | | | | | |
| [Matomo](https://git.autonomic.zone/coop-cloud/matomo) | ❸🍎 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❌ |
| [Matrix (Synapse)](https://git.autonomic.zone/coop-cloud/matrix-synapse) | ❹💣 | ❶💚 | ✅ | ❌ | ❌ | ❌ | ❌ |
| [Mediawiki](https://git.autonomic.zone/coop-cloud/mediawiki) | ❸🍎 | ❶💚 | ❌ | ✅ | ❶💚 | ❷💛 | ❷💛 (OAuth, SAML) |
| [monica](https://git.autonomic.zone/coop-cloud/monica) | | ❶💚 | no | no | ❶💚 | ❷💛 | no |
| [mumble](https://git.autonomic.zone/coop-cloud/mumble) | ❸🍎 | ❸🍎3rdparty | ❌ | ❌ | ⛔ | ❌ | ⛔ |
| [Nextcloud](https://git.autonomic.zone/coop-cloud/nextcloud) | ❷💛 | ❶💚 | ✅ | ❌ | ❶💚 | ❷💛 | ❸🍎 (OAuth) |
| [notea](https://git.autonomic.zone/coop-cloud/notea) | ❹💣 | [`notea`](https://hub.docker.com/r/cinwell/notea) | ❌ | ❌ | ❌ | ❌ | ❌ |
| [oasis](https://git.autonomic.zone/coop-cloud/oasis) | 0, work-in-progress | | | | | | |
| [onlyoffice](https://git.autonomic.zone/coop-cloud/onlyoffice) | ❶💚 | ❶💚 | ❌ | ❌ | ❶💚 | ❷💛 | ❌ |
| [Osticket](https://git.autonomic.zone/coop-cloud/osticket) | 0, work-in-progress | [`osticket`](https://hub.docker.com/r/osticket/osticket) | | | | | |
| [Outline](https://git.autonomic.zone/coop-cloud/outline) | | [outlinewiki/outline](https://hub.docker.com/r/outlinewiki/outline) | | | | | |
| [Pelican](https://git.autonomic.zone/coop-cloud/pelican) | ❷💛 | ❹💣 | ❌ | ❌ | ⛔ | ❷💛 | ❌ |
| [Penpot](https://git.autonomic.zone/coop-cloud/penpot) | ❹💣 | [`penpotapp/*`](https://hub.docker.com/r/penpotapp) | | | | | |
| [PHP / LEMP](https://git.autonomic.zone/coop-cloud/lemp) | ❶💚 | ❶💚 | ✅ | ✅ | ❶💚 | ❷💛 | ❌ |
| [PHPServerMon](https://git.autonomic.zone/coop-cloud/phpservermon) | 0, work-in-progress | ❸🍎 | | ❌ | ❌ | ❌ | ❌ |
| [plausible](https://git.autonomic.zone/coop-cloud/plausible) | 1, alpha | ❶💚 | | | | | |
| [Projectsend](https://git.autonomic.zone/coop-cloud/projectsend) | 0, work-in-progress | ❸🍎 | ✅ | ❌ | ❌ | ❌ | ❌ |
| [Radicale](https://git.autonomic.zone/coop-cloud/radicale) | ❹💣 | ❸🍎 | ✅ | ❌ | ❌ | ❌ | ❌ |
| [Rocket.chat](https://git.autonomic.zone/coop-cloud/rocketchat) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❶💚 (OAuth) |
| [Rstudio](https://git.autonomic.zone/coop-cloud/rstudio) | | [`rstudio`](https://hub.docker.com/r/rstudio/rstudio) | | | | | |
| [Selfoss](https://git.autonomic.zone/coop-cloud/selfoss) | ❸🍎 | ❸🍎 | ✅ | ❌ | ❌ | ❸🍎 | ⛔ |
| [singlelink](https://git.autonomic.zone/coop-cloud/singlelink) | 0, work-in-progress | | | | | | |
| [snikket](https://git.autonomic.zone/coop-cloud/snikket) | | [`thecoopcloud/snikket-*`](https://hub.docker.com/u/thecoopcloud) | | | | | |
| [Statping](https://git.autonomic.zone/coop-cloud/statping) | ❸🍎 | ❶💚 | ❌ | ❌ | ❸🍎 | ❌ | ❌ |
| [Statuspal](https://git.autonomic.zone/coop-cloud/statuspal) | 0, work-in-progress | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [Strapi](https://git.autonomic.zone/coop-cloud/strapi) | ❸🍎 | ❶💚 | ❌ | ❌ | ❌ | ❷💛 | ❌ |
| [vaultwarden](https://git.autonomic.zone/coop-cloud/vaultwarden) | | | | | | | |
| [Wallabag](https://git.autonomic.zone/coop-cloud/wallabag) | ❸🍎 | ❶💚 | ❌ | ❌ | ❌ | ❷💛 | ❌ |
| [Wordpress](https://git.autonomic.zone/coop-cloud/wordpress) | ❶💚 | ❶💚 | ✅ | ✅ | ❶💚 | ❷💛 | ❌ |
| [Workadventure](https://git.autonomic.zone/coop-cloud/workadventure) | ❹💣 | [`thecodingmachine/workadventure*`](https://hub.docker.com/r/thecodingmachine/) | ❌ | ❌ | ❌ | ❌ | ❌ |
| [ZNC](https://git.autonomic.zone/coop-cloud/znc) | ❹💣 | ❸🍎 | ❌ | ❌ | ❌ | ❌ | ❌ |
## Utilities
| **Name** | **Status** | **Image** | **Healtcheck** | **Backups** | **Email** | **CI** | **Single-Sign-On** |
| --- | --- | --- | --- | --- | --- | --- | --- |
| [AWX](https://git.autonomic.zone/coop-cloud/AWX) | 0, work-in-progress | | | | | | |
| [Backupbot II](https://git.autonomic.zone/coop-cloud/backup-bot-two) | 0, work-in-progress | 4 | ❌ | ⛔ | ⛔ | ❌ | ⛔ |
| [container](https://git.autonomic.zone/coop-cloud/container) | 1, alpha | any | ❌ | ❌ | ❌ | ❌ | ❌ |
| [croc](https://git.autonomic.zone/coop-cloud/croc) | ❶💚 | ❶💚 | ❌ | ❌ | ❌ | ❌ | ❌ |
| [distribution](https://git.autonomic.zone/coop-cloud/distribution) | 0, work-in-progress | ❶💚 | ? | ? | ? | ? | ? |
| [Docker-Hub-RSS](https://git.autonomic.zone/coop-cloud/docker-hub-rss) | ? | ❶💚 | ? | ? | ? | ? | ? |
| [drone-docker-runner](https://git.autonomic.zone/coop-cloud/drone-docker-runner) | 1, alpha | ❶💚 | ? | ? | ? | ? | ? |
| [go-neb](https://git.autonomic.zone/coop-cloud/go-neb) | ❹💣 | ❶💚 | | | | | |
| [go-ssb-room](https://git.autonomic.zone/coop-cloud/go-ssb-room) | ❹💣 | ❹💣 | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [Jupyter Lab](https://git.autonomic.zone/coop-cloud/n8n) | 1 | `n8nio/n8n` | ❌ | ❌ | ⛔ | ❌ | ❌ |
| [keycloak-collective-portal](https://git.autonomic.zone/coop-cloud/keycloak-collective-portal) | 1, alpha | [`decentral1se/keycloak-collective-portal`](https://hub.docker.com/r/decentral1se/keycloak-collective-portal) | ✅ | ❌ | ⛔ | ✅ | ⛔ |
| [minio](https://git.autonomic.zone/coop-cloud/minio) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ❌ |
| [portainer](https://git.autonomic.zone/coop-cloud/portainer) | ? | ❶💚 | ❌ | ? | ? | ❷💛 | ❌ |
| [Postfix-Relay](https://git.autonomic.zone/coop-cloud/postfix-relay) | ❷💛 | ❶💚 | ✅ | ❌ | ⛔ | ❷💛 | ⛔ |
| [renovate](https://git.autonomic.zone/coop-cloud/renovate) | | | | | | | |
| [swarm-cronjob](https://git.autonomic.zone/coop-cloud/swarm-cronjob) | ? | ❶💚 | ? | ? | ? | ? | ? |
| [Swarmpit](https://git.autonomic.zone/coop-cloud/swarmpit) | ❷💛 | ❶💚 | ✅ | ❌ | ❌ | ❷💛 | ⛔ |
| [traefik-forward-auth](https://git.autonomic.zone/coop-cloud/traefik-forward-auth) | ? | ❶💚 | ? | ? | ? | ? | ? |
| [Traefik](https://git.autonomic.zone/coop-cloud/traefik) | ? | ❶💚 | ✅ | ❌ | ⛔ | ❷💛 | ? (Keycloak) |
## Status legend
### Overall
- 🌈🌈: everything in ❶💚 + Single-Sign-On
- ❶💚: upstream image, backups, email, healthcheck, integration testing
- ❷💛: upstream image, missing 1-2 items from ❶💚
- ❸🍎: missing 3-4 items from ❶💚 or no upstream image
- ❹💣: alpha
### Image
- ❶💚: official upstream image
- ❷💛: semi-official / actively-maintained image
- ❸🍎: 3rd-party image
- ❹💣: our own custom image
### Email
- ❶💚: automatic (using environment variables)
- ❷💛: mostly automatic
- ❸🍎: manual
- ❌: none
### CI
- ❶💚: as ❷💛, plus healthcheck
- ❷💛: auto secrets + networks
- ❸🍎: basic deployment using `stack-ssh-deploy`, manual secrets + networks
- ❌: none
### Single-Sign-On
- ❶💚: automatic (using environment variables)
- ❷💛: mostly automatic
- ❸🍎: manual
- ❌: none
- 💣: not supported

61
docs/x-archive/backup-restore.md Normal file
View File

@ -0,0 +1,61 @@
---
title: Back-up and restore an app
---
We'll use the example of a [`coop-cloud/wordpress`][wordpress] app deployed at
`blog.example.com`.
## Backing up
```
abra app wordpress_blog_example_com backup --all
```
This will download backups of the Wordpress files (plugins, themes, and uploads)
and database (posts, settings and users) to the default backup directory,
`~/.abra/backups`.
You can also back up just the files:
```
abra app wordpress_blog_example_com backup app
```
or just the database:
```
abra app wordpress_blog_example_com backup db
```
!!! warning
Not all types of apps know how to do backups yet -- if you see a message
like `ERROR: 'nextcloud' doesn't know how to do app backups`, then extra
code is needed in that app's `abra.sh` -- you might be able to add this
yourself based on [`coop-cloud/wordpress` `abra.sh`][wordpress_abra.sh],
otherwise please open a new issue (in this case for
[`coop-cloud/nextcloud`][nextcloud]).
## Restore
You can restore data into a running application. This is useful to restore an
app to a previous state, to migrate an app from one Co-op Cloud server to
another, or to help move an app to Co-op Cloud initially.
Using the same example app above, you can restore files:
```
abra app wordpress_blog_example_com restore app blog_example_com_app.tar.gz
```
and/or the database:
```
abra app wordpress_blog_example_com restore db blog_example_com_db.sql.gz
```
(there isn't yet a command to restore files and database data at the same time)
[wordpress]: https://git.autonomic.zone/coop-cloud/wordpress
[wordpress_abra.sh]: https://git.autonomic.zone/coop-cloud/wordpress/src/branch/master/abra.sh
[nextcloud]: https://git.autonomic.zone/coop-cloud/nextcloud

9
docs/x-archive/bikemap.md Normal file
View File

@ -0,0 +1,9 @@
---
title: Bike map
---
- The project is currently in an [alpha quality](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) release state.
- We are working towards a [beta release](https://en.wikipedia.org/wiki/Software_release_life_cycle#Beta).
- We do not currently have an exact for the public Beta release yet.
- Our public Beta goals are listed in the following pad: [beta bike map](https://pad.autonomic.zone/s/C3uuqfSCk)
- What we're currently working on is listed on this issue tracker: [`coop-cloud/organising`](https://git.autonomic.zone/coop-cloud/organising/issues)

35
docs/x-archive/comm-org.md Normal file
View File

@ -0,0 +1,35 @@
---
title: Community Organising
---
## Monthly updates on progress
We have decided we'll try to do monthly progress updates. These will be published on the Co-op Cloud blog.
It's a pretty loose format and we're basically just copy/pasta'ing things to a public pad during the month:
> [This month in Co-op Cloud](https://pad.autonomic.zone/YHKn4vHORmS6wjN1t2zi5A?both)
Feel free to add your items to the monthly agenda and they will be included!
## Kite Flying Hours
The "Kite Flying Hour" is a weekly public moment where anyone can "drop by" into a Jitsi call and ask/do/propose whatever and meet some people who are currently working on the project. We haven't worked it all out but our process for now is the following:
- Someone from Autonomic will volunteer to be present and talk about the project for an hour weekly from 15:00 CEST - 16:00 CEST
- We announce the hour via our socials
- A [pinned toot](https://social.coop/web/statuses/106528094828958420) on [`@coopcloud@social.coop`](https://social.coop/@coopcloud)
- A [pinned tweet](https://twitter.com/Coop_Cloud/status/1412028519056609286) on [`@Coop_Cloud`](https://twitter.com/Coop_Cloud)
- A post to the `#coopcloud:autonomic.zone` room
Here is some invitation boilerplate which you can use:
> Hey folks, you're all warmly invited to the Co-op Cloud Kite Flying Hour at `$X_TIME` `$Y_TZ` `$Z_DATE` over in [meet.jit.si/CoopCloudKiteFlyingHour](https://meet.jit.si/CoopCloudKiteFlyingHour)!
>
> Inspired by exquisite childhood memories of [flying kites, eating popsicles and looking at clouds](https://norwichhistory.org/norwich-a-z-j-is-for-jigsaw/), it's an open hour to come hang out online and discuss/co-work/lurk/etc. around the [Co-op Cloud](https://coopcloud.tech/) project.
>
> There are no "stupid questions"! It's a space to inquire, be curious and have a good time and get to know each other.
>
> We take notes and doodle on [this collaboratively editable pad](https://pad.autonomic.zone/LqotfSJJRj69RcTtWmr7iw). If you don't have time to attend, feel free to drop your questions and some contact details also, so we can get in touch. This is only the first Kite Flying Hour in a recurring series of Kite Flying Hours.
>
> Hope to see you there! ☁️ 🌞 🖥️

108
docs/x-archive/config.md Normal file
View File

@ -0,0 +1,108 @@
---
title: Manage your app configuration
---
## Understanding app and server configuration
Co-op Cloud stores per-app configuration in the `$USER/.abra/servers` directory, on whichever machine you're running `abra` on (by default, your own workstation).
The format of these configuration files is the same environment variable syntax used by Docker (with the `env_file:` statement in a `docker-compose.yml` file, or the `--env-file` option to `docker run`) and `direnv`:
```
abra app example_wordpress config
TYPE=wordpress
DOMAIN=wordpress.example.com
## Domain aliases
EXTRA_DOMAINS=', `www.wordpress.example.com`'
LETS_ENCRYPT_ENV=production
...
```
`abra` doesn't mind if `~/.abra/servers`, or any of its subdirectories, is a [symlink], so you can keep your app definitions wherever you like!
```
mv ~/.abra/servers/ ~/coop-cloud
ln -s ~/coop-cloud ~/.abra/servers
```
## Backing up your app configuration
Just make sure the `~/.abra/servers` is included in the configuration of your favourite backup tool.
You can optionally also backup `~/.abra/apps`, if you'd like to keep an exact copy of the application versions you currently have deployed. Otherwise, they'll be automatically downloaded the first time you run an `abra app...` command.
You don't need to worry about `~/.abra/vendor` or `~/.abra/src` directories, which will be likewise recreated automatically as and when you need them.
<a id="version-control"></a>
## Version-control your app configs (using git)
Because `~/.abra/servers` is a collection of plain-text files, it's easy to keep your backup configuration in a version control system (we use `git`, others would almost certainly work).
This is particularly recommended if you're collaborating with others, so that you can all run `abra app...` commands without having to maintain your own separate, probably-conflicting, configuration files.
In the simple case where you only have one server configured with `abra`, or everyone in your team is using the same set of servers, you can version-control the whole `~/.abra/servers` directory:
```
cd ~/.abra/servers
git init
git add .
git commit -m "Initial import"
```
!!! warning "Test your revision-control self-discipline"
`abra` does not yet help keep your app definitions are up-to-date.
Make sure to run `git add` / `git commit` after making configuration changes, and `cd ~/.abra/servers && git pull` before running `abra app...` commands.
Patches to add some safety checks and auto-updates would be very welcome! 🙏
## Collaborating with multiple teams
In a more complex situation, where you're using Co-op Cloud to manage several servers, and you're collaborating with different people on different servers, you can set up **a separate repository for each subdirectory in `~/.abra/servers`**, or even a mixture of single-server and multi-server repositories:
```
ls -l ~/.abra/servers
# Example.com's own app configuration:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.example.com -> /home/user/Example/coop-cloud-apps/swarm.example.com
# Configuration for one of Example.com's clients – part of the same repository:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.client.com -> /home/user/Example/coop-cloud-apps/swarm.client.com
# A completely separate project, part of a different repository:
lrwxrwxrwx. 1 user user 49 Oct 30 22:42 swarm.demonstration.com -> /home/user/Demonstration/coop-cloud-apps
```
To make setting up these symlinks easier, you might want to include a simple installer script in your configuration repositories.
We don't have a public example of this yet, but something like this should do the trick:
1. Save this as `Makefile` in your repository:
```
# -s symlink, -f force creation, -F don't create symlink in the target dir
link:
@mkdir -p ~/.abra/servers/
@for SERVER in $$(find -maxdepth 1 -type d -name "[!.]*"); do \
echo ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
ln -sfF "$$(pwd)/$${SERVER#./}" ~/.abra/servers/ ; \
done
```
This will set up symlinks from each directory in your repository to a correspondingly-named directory in `~/.abra/servers` – if your repository has a `swarm.example.com` directory, it'll be linked as `~/.abra/servers/swarm.example.com`.
2. Tell your collaborators (e.g. in the repository's `README`), to run `make` in their repository check-out.
!!! warning "You're on your own!"
As with the [simple repository set-up above](#version-control), `abra` doesn't yet help you update your version control system when you make changes, nor check version control to make sure you have the latest configuration.
Make sure to `commit` and `push` after you make any configuration changes, and `pull` before running any `abra app...` commands.
## Even more granularity?
The plain-text, file-based configuration format means that you could even keep the configuration for different apps on the same server in different repositories, e.g. having `git.example.com` configuration in a separate repository to `wordpress.example.com`, using per-file symlinks.
We don't currently recommend this, because it might set inaccurate expectations about the security model – remember that, by default, **any user who can deploy apps to a Docker Swarm can manage _any_ app in that swarm**.
[symlink]: https://en.wikipedia.org/wiki/Symlink

12
docs/x-archive/contact.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Get in Touch
---
We're available on the following channels:
- **Email**: [`helo@coopcloud.tech`](mailto:helo@coopcloud.tech)
- **Real-time chat (Matrix)**:
- [`#coopcloud:autonomic.zone`](https://matrix.to/#/!JSVYWCRXSVMrAzgeKB:autonomic.zone?via=autonomic.zone) General chat and announcements (low traffic)
- [`#coopcloud-tech:autonomic.zone`](https://matrix.to/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Technical discussions (some techno babble)
- [`#coopcloud-dev:autonomic.zone`](https://matrix.to/#/!IFazIpLtxiScqbHqoa:autonomic.zone?via=autonomic.zone) Intense developer chat (a lot of techno babble)
- **Forum**: [`community.coops.tech`](https://community.coops.tech/)

39
docs/x-archive/contribute.md Normal file
View File

@ -0,0 +1,39 @@
---
title: Contributing guide
---
> You don't have to be a programmer to contribute to this project!
Firstly, come say hello in our [chat room](/contact/) if you'd like to help out
:wave: We are happy to have designers, thinkers, hackers, documenters, etc.
involved in this project! There is a lot of work to do, if you find this
project interesting, we want to have you working with us.
We have [a weekly check-in](/comm-org/#kite-flying-hours) for contributors of
this project to let each other know what we're working on, how much time we've
spent on it and how to coordinate further work.
We have a [public bike map](https://pad.autonomic.zone/s/C3uuqfSCk) showing
what we are aiming to achieve in the near future. That gives a good overview
of where we're going together.
From this bike map, we use an [issue
tracker](https://git.coopcloud.tech/coop-cloud/organising/issues) where we hold
discussions about what we want to do. We categorise these issues according to
the bike map using these
[milestones](https://git.coopcloud.tech/coop-cloud/organising/milestones).
Finally, use this
[board](https://git.coopcloud.tech/coop-cloud/organising/projects/8) to keep
track of what we're working on right now. We collectively review these things
on a weekly/monthly basis to keep track of our time spent vs. budget available.
Once you've found something to work on and are introduced, we'll give you an
account on our [time tracking infrastructure](https://kimai.autonomic.zone)
where you can log your times. This helps us reduce the burden of financial and
time keeping admin falling on one person.
We have received funding via [the
ECF](https://culturalfoundation.eu/initiatives/culture-of-solidarity-fund) and
can offer £16 hourly rate for your work. We've written
[more](/strategy/#compensation-for-contributions) on why we think it is
important to compensate all contributions for this project.

11
docs/x-archive/credits.md Normal file
View File

@ -0,0 +1,11 @@
---
title: Credits & thanks
---
> _The real Co-op Cloud was the friends we made along the way 🌠_
Special thanks to:
- [Doop Coop](mailto:cluck@doop.coop), for making a transparent version of the Co-op Cloud logo, and helping with OSX alpha testing.
- [Social.coop](https://social.coop), for warmly welcoming us onto [`social.coop/@coopcloud`](https://social.coop/@coopcloud).
- [Servers.coop](https://servers.coop), for hosting our digital infrastructure (website, builds, git hosting, etc.).

145
docs/x-archive/deploy.md Normal file
View File

@ -0,0 +1,145 @@
---
title: Deploy your first app
---
In order to deploy an app you need two things:
1. a server (e.g. [Hetzner VPS](https://www.hetzner.com/cloud)), with
- SSH access
- a public IP address
2. a DNS provider (e.g. [Gandi](https://www.gandi.net/en))
## Create your server
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](/faq/#isnt-running-everything-in-containers-inefficient)). 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](/faq/#arent-containers-horrible-from-a-security-perspective) if you are curious about security in the context of containers.
## Wire up your DNS
Typically, you'll need two A records, one to point to the VPS itself and another to support sub-domains for the apps. You can then support an app hosted on your root domain (e.g. `example.com`) and other apps on sub-domains (e.g. `foo.example.com`, `bar.example.com`). Your entries in your DNS provider setup might look like the following.
@ 1800 IN A 116.203.211.204
*. 1800 IN A 116.203.211.204
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/) on your server. This can be done by following the [install documentation](https://docs.docker.com/engine/install/).
## Bootstrap `abra`
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.
```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/scripts/installer/installer).
the installer will verify the checksum. If you want to download abra yourself, you can grab it from the [releases page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the checksums.txt file. If you decide to do this, please run:
```bash
grep $(sha256sum abra_[version]_[platform]) checksums.txt > /dev/null && echo "checksum OK"
```
if "checksum OK" appears in your terminal - you're good to go! otherwise, you have downloaded a corrupted file.
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 -h # check it works
```
Now you can connect `abra` with your new server.
```bash
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:
```bash
abra server add -p example.com username 2222
```
The `-p` or `--provision` flag means that abra will initialise the [new single-host swarm](https://docs.docker.com/engine/swarm/key-concepts/) on your server.
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
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 traefik
```
You will want to take a look at your generated configuration and tweak the `LETS_ENCRYPT_EMAIL` value:
```bash
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 deploy traefik
```
## Deploy Nextcloud
And now we can deploy apps.
Let's create a new Nextcloud app.
```bash
abra app new nextcloud
```
And we need to generate secrets for the app: database connection password, root password and admin password.
```bash
abra app secret generate --all nextcloud
```
!!! 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](/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 deploy nextcloud
```
We can watch to see that things come up correctly.
```bash
abra app ps nextcloud # status check
abra app logs nextcloud # logs watch
```
!!! note
Since Nextcloud takes some time to come up live, you can run the `ps`
command under `watch` like so.
```bash
watch abra app ps nextcloud
```
And you can wait until you see that all containers have the "Running" state.
Your `traefik` instance will detect that a new app is coming up and generate SSL certificates for it.

253
docs/x-archive/faq.md Normal file
View File

@ -0,0 +1,253 @@
---
title: Frequently asked questions
---
## What is the Co-op Cloud?
Co-op Cloud aims to make hosting libre software apps simple for small service providers such as tech co-operatives who are looking to standardise around an open, transparent and scalable infrastructure. It uses the latest container technologies and configurations are shared into [the commons](https://en.wikipedia.org/wiki/Commons) for the benefit of all.
## Who is behind the project?
The project was started by workers at [Autonomic](https://autonomic.zone/) which is a [worker-owned co-operative](https://en.wikipedia.org/wiki/Worker_cooperative). We provide technologies and infrastructure to empower users to make a positive impact on the world. We're using Co-op Cloud in production, amongst other systems.
## Why Co-op Cloud?
#### 👍
- 👍 Thin "ease of use" layer on top of already standardised tooling
- 👍 Extremely modular
- 👍 Collective commons based configuration via public git repos
- 👍 Focussed on hosting providers
- 👍 Uses upstream published containers (no duplication on packaging)
- 👍 Now and always libre software
- 👍 Command line focussed
- 👍 Horizontal and vertical scaling
#### 👎
- 👎 Still a very young project
- 👎 Limited availability of well tested apps
- 👎 Requires command line knowledge to use
- 👎 Currently x86 only (see [this FAQ question](#why-only-x86-support) for more)
## Why start another project?
Please read our [initial project announcement post](https://autonomic.zone/blog/co-op-cloud/) for more on this.
Also see our [strategy page](/strategy/).
## How do I package an app?
See [the packager guide documentation](/packager-guide/#package-your-first-application) for more.
## What about `$alternative`?
We have various technical critiques of other similar projects which are already up-and-running in the ecosystem, as they don't necessarily meet our needs as a small tech co-op. However, Co-op Cloud isn't meant to be a replacement for these other projects.
Here is a short overview of the pros/cons we see, in relation to our goals and needs.
### Cloudron
#### 👍
- 👍 Decent web interface for app, domain & user management.
- 👍 Large library of apps.
- 👍 Built-in SSO using LDAP, which is compatible with more apps and often has a better user interface than OAuth.
- 👍 apps are actively maintained by the Cloudron team.
#### 👎
- 👎 Moving away from open source. The core is now proprietary software.
- 👎 libre tier has a single app limit.
- 👎 Based on Docker images, not stacks, so multi-process apps (e.g. parsoid visual editor for Mediawiki) are a non-starter.
- 👎 Difficult to extend apps.
- 👎 Only supported on Ubuntu LTS.
- 👎 Upstreams libre software communities aren't involved in packaging.
- 👎 Limited to vertical scaling.
- 👎 Tension between needs of hosting provider and non-technical user.
- 👎 LDAP introduces security problems - one vulnerable app can expose a user's password for all apps.
- 👎 Bit of a [black box](https://en.wikipedia.org/wiki/Black_box).
### YunoHost
#### 👍
- 👍 Lovely web interface for app, domain & user management.
- 👍 Bigger library of apps.
- 👍 Awesome backup / deploy / restore continuous integration testing.
- 👍 Supports hosting apps in subdirectories as well as subdomains.
- 👍 Doesn't require a public-facing IP.
- 👍 Supports system-wide mutualisation of resources for apps (e.g. sharing databases by default)
#### 👎
- 👎 Upstream libre software communities aren't involved in packaging.
- 👎 Uninstalling apps leaves growing cruft.
- 👎 Limited to vertical scaling.
- 👎 Not intended for use by hosting providers.
### Caprover
#### 👍
- 👍 Bigger library of apps.
- 👍 Easy set-up using a DigitalOcean one-click app.
- 👍 Works without a domain name or a public IP, in non-HTTPS mode (good for homeservers).
- 👍 Deploy any app with a `docker-compose.yml` file as a "One Click App" via the web interface.
- 👍 Multi-node (multi-server) set-up works by default.
#### 👎
- 👎 Single-file app definition format, difficult to tweak using entrypoint scripts.
- 👎 Nginx instead of Traefik for load-balancing.
- 👎 Command-line client requires NodeJS / `npm`.
- 👎 [Requires 512MB RAM for a single app](https://github.com/caprover/caprover/issues/28).
- 👎 [Backup/restore is "experimental"](https://caprover.com/docs/backup-and-restore.html), and doesn't currently help with backing up Docker volumes.
- 👎 Exposes its bespoke management interface to the internet via HTTPS by default.
### Ansible
#### 👍
- 👍 Includes server creation and bootstrapping.
#### 👎
- 👎 Upstream libre software communities aren't publishing Ansible roles
- 👎 Lots of manual work involved in things like app isolation, backups, updates
### Kubernetes
#### 👍
- 👍 Helm charts are available for some key apps already.
- 👍 Scale all the things.
#### 👎
- 👎 Too big -- requires 3rd party tools to run a single-node instance.
- 👎 Not suitable for a small to mid size hosting provider.
### Docker-compose
#### 👎
- 👎 Manual work required for process monitoring.
- 👎 Secret storage not available yet.
- 👎 [Swarm is the new best practice](https://github.com/BretFisher/ama/issues/8#issuecomment-367575011).
### Doing it Manually (Old School)
#### 👍
- 👍 Simple - just follow upstream instructions to install and update.
#### 👎
- 👎 Loads of manual work required for app isolation and backups.
- 👎 Array of sysadmin skills required to install and maintain apps.
- 👎 Hard to share configurations into the commons.
- 👎 No idea who has done what change when.
## Which technologies are used?
The core technologies of Co-op Cloud are libre software and enjoy wide adoption across software developer communities.
- [Containers](#why-containers)
- [Compose specification](#why-docker-compose)
- [Docker swarm](#why-docker-swarm)
- [Abra command-line tool](https://git.autonomic.zone/coop-cloud/abra)
## Why containers?
We use containers because so many libre software communities choose to use them. They are already writing and using Docker files and Docker-compose definitions for their development and production environments.
We can directly re-use this good packaging work and contribute back by helping maintain their in-repository files. We meet them where they are at and do not create a new packaging format or duplicate effort.
Co-op cloud proposes the idea of more direct coordination between distribution (app packagers) and production (developers) methods.
## Aren't containers horrible from a security perspective?
It depends, just like any other technology and understanding of security. Yes, we've watched [that CCC talk](https://media.ccc.de/v/rc3-49321-devops_disasters_3_1).
It's on us all as the libre software community to deliver secure software and we think one of the promises of Co-op Cloud is better cooperation with developers of the software (who favour containers as a publishing format) and packagers and hosters (who deliver the software to the end-user).
This means that we can patch our app containers directly in conversation with upstream app developers and work towards a culture of security around containers.
We definitely recommend using best-in-class security auditing tools like [docker-bench-security](https://github.com/docker/docker-bench-security), IDS systems like [OSSEC](https://www.ossec.net/), security profiles like [Apparmor](https://docs.docker.com/engine/security/apparmor/) and hooking these into your existing monitoring, alert and update maintenance flows.
It's up to how you want to arrange your system. For example, Co-op Cloud also allows you to compartmentalise different apps onto different servers. You could stack a bunch of apps on one big server or you could deploy one app per server.
These are organisational concerns that Co-op Cloud can't solve for you which any software system will require. See this [additional question](/faq/#what-is-important-to-consider-when-running-containers-in-production) for further information.
## What is important to consider when running containers in production?
The Co-op Cloud uses [containers](/faq/#why-containers) as a fundamental building block. Therefore it is important to be aware of some general principles for container management in production environments. These are typically things that you will want to discuss within your co-op or democratic collective about how to prioritise and build up process for.
However, as the Co-op Cloud project is still very young, we're also still thinking about how we can make the platform itself mitigate problematic issues and make the maintenance of containers a more stable experience.
With that all in mind, here are some leading thoughts.
- How do you install the Docker daemon itself on your systems and how do you manage upgrades? (system package, upstream Docker Inc. repository?)
- How do you secure the Docker daemon from remote access (firewalls and system access controls).
- How do you secure the Docker daemon socket within the swarm (locking the socket down, using things like a [socket proxy](https://github.com/Tecnativa/docker-socket-proxy))
- How do you trust the upstream container registry (there are [content trust mechanisms](https://docs.docker.com/engine/security/trust/) but it seems also useful to think about whether we need community registry infrastructure using tools like [harbor](https://goharbor.io/) or [distribution](https://github.com/distribution/distribution). This involves a broader discussion with upstream communities.)
- How do I audit my container security in an on-going process (IDS, OSSEC, Apparmor, etc.)
- Can I run my containers with a [non-root user setup](https://docs.docker.com/engine/security/rootless/)?
And further reading on this topic:
- [Docker security documentation](https://docs.docker.com/engine/security/)
- [OWASP Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)
## Why use the Compose specification?
Every app packaged for the Co-op Cloud is described using a file format which uses the [compose specification](https://compose-spec.io/). It is important to note that we do not use the [Docker compose](https://docs.docker.com/compose/) tool itself to deploy apps using this format, instead we rely on [Docker swarm](https://docs.docker.com/engine/swarm/stack-deploy/).
The compose specification is a useful open standard for specifying libre software app deployments in one file. It appears to be the most accessible format for describing apps and this can be seen in the existence of tools like [Kompose](https://kompose.io/) where the compose format is used as the day-to-day developer workflow format which is then translated into more complicated formats for deployment.
We are happy to see the compose specification emerging as a new open standard because that means we don't have to rely on Docker Inc. in the future - there will be more community tools available.
## Why Docker Swarm?
While many have noted that "swarm is dead" it is in fact [not dead](https://www.mirantis.com/blog/mirantis-will-continue-to-support-and-develop-docker-swarm/). As detailed in the [architecture overview page](/overview/#container-orchestrator), swarm offers an appropriate feature set which allows us to support zero-down time upgrades, seamless app rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design.
While the industry is bordering on a [k8s](https://kubernetes.io/) obsession and the need to [scale down](https://microk8s.io/) a tool that was fundamentally built for massive scale, we are going with swarm because it is the tool most suitable for [small technology](https://small-tech.org/).
We hope to see a container orchestrator tool that is not directly linked to a for-profit company emerge soon but for now, this is what we have.
If you want to learn more, see [dockerswarm.rocks](https://dockerswarm.rocks/) for a nice guide.
## What licensing model do you use?
The Co-op Cloud is and will always be available under [copyleft licenses](https://en.wikipedia.org/wiki/Copyleft).
We're discussing more specifics on [this issue](https://git.autonomic.zone/coop-cloud/organising/issues/50) if you'd like to see the on-going conversation.
## Isn't running everything in containers inefficient?
It is true that if you install 3 apps and each one requires a MySQL database, then you will have 3 installations of MySQL on your system, running in containers.
Systems like [YunoHost](/faq/#yunohost) mutualise every part of the system for maximum resource efficiency - if there is a MySQL instance available on the system, then just make a new database there and share the MySQL instance instead of creating more.
However, as we see it, this creates a tight coupling between apps on the database level - running a migration on one app where you need to turn the database off takes down the other apps.
It's a balance, of course. In this project, we think that running multiple databases and maintaining more strict app isolation is worth the hit in resource efficiency.
It is easier to maintain and migrate going forward in relation to other apps and problems with apps typically have a smaller problem space - you know another app is not interfering with it because there is no interdependency.
It can also pay off when dealing with GDPR related issues and the need to have more stricter data layer separation.
## How do I keep up-to-date with Docker Swarm developments?
- [Official release changelog for Docker Engine (look for entries under the "Swarm" header)](https://docs.docker.com/engine/release-notes/)
- [All issues raised with label `area/swarm` label on github.com/moby/moby](https://github.com/moby/moby/issues?q=is%3Aopen+is%3Aissue+label%3Aarea%2Fswarm)
- [All pull requests submitted with the `area/swarm` label on github.com/moby/moby](https://github.com/moby/moby/pulls?q=is%3Aopen+is%3Apr+label%3Aarea%2Fswarm)
## Can I run Co-op Cloud on multiple servers?
Yes! Horizontal scaling is one of the ways Co-op Cloud can really shine. `abra` is designed to handle multiple servers from the first day. As long as you have a DNS entry pointing to your server then Co-op Cloud can serve apps (e.g. you can serve a `wordpress1.mydomain.com` from one server and a `wordpress2.mydomain.com` from another server) and `abra` handles this seamlessly.
## Why only x86 support?
We would love to do ARM support and hope to get there! We've been testing this and [ran into some issues](https://git.autonomic.zone/coop-cloud/organising/issues/25). The TLDR; is that a lot of upstream libre app developer communities are not publishing container builds that support ARM. If they are, there are typically subtle differences in the conventions used to build the image as they are mostly done by community members and not directly taken on by the upstream project themselves. Since one of the core goals is to coordinate and reuse upstream packaging work, we see that ARM support requires a lot of organising and community engagement. Perhaps projects themselves will not want to take on this burden? It is not the role of the Co-op Cloud to set up an entire ARM publishing work flow at this moment in time. We see the benefits of supporting ARM and if you've got ideas / thoughts / approaches for how to make progress here, [please get in touch](https://docs.coopcloud.tech/contact/).

29
docs/x-archive/glossary.md Normal file
View File

@ -0,0 +1,29 @@
---
title: glossary
---
abra-related words
- recipe - a git repository with files describing to abra how to assemble an application
- application - an instance of a recipe composed of one or more services and running as a docker stack
- service - a single docker container that is a part of a stack, configured in compose.yml and .env files
- deployment - the act of assembling a docker stack described by a recipe and application configuration
docker-related words:
- image - a template for creating containers, describing their file structure, installed binaries etc.
- container - an instance of an image, running processes that are isolated from the host system
- environment variables - variables passed from the shell to processes invoked by it. used for configuring services.
- .env file - a file describing the contents of environmental variables
- network - a virtual network created on the server machine used for communicating between services (containers). Any service can be plugged into more than one network, allowing for control over data sharing between them.
- secret - docker uses those for securely storing data such as passwords. They are stored encrypted on disk and mounted inside the containers as files that can be read that contain the secret.
- stack - one or more services (containers) running together to provide a functionality.
- volume - a directory that can be mounted inside a docker container to store data. Because containers are meant to be non-changeable and disposable, any data that is supposed to not be lost between updates or restarts is stored in volumes.
"mappings" between those concepts:
- abra app = docker stack
- abra recipe = set of docker images in `compose` format
- abra service = docker stack service

21
docs/x-archive/index.md Normal file
View File

@ -0,0 +1,21 @@
---
title: Co-op Cloud
---
Welcome to the Co-op Cloud technical documentation. It's primarily meant for co-ops and other democratic tech collectives already doing libre software hosting who are interested in the project and thinking about doing some alpha testing.
- New to the project and wondering where to start? Try our [getting started guide](/overview/).
- Want to see what apps are already available? See the [app catalogue](https://dev.apps.coopcloud.tech).
- Trying to understand more about the project? See the [the FAQ](/faq/).
- Interested to learn more about the goals and background of the project? See the [strategy page](/strategy).
!!! danger "Here be dragons"
This project is still [alpha quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha). Please take that into consideration if you are thinking about using this system in production. We're working hard to make Co-op Cloud stable. In the meantime, this is a good time to help us out with initial testing, feedback, ideas or [join in with development](/contribute/).
!!! note "Looking for managed Co-op Cloud hosting?"
If you're looking for a co-operative or tech collective to host digital services for you using the Co-op Cloud, then please see [the managed hosting](/managed/) page for more.

13
docs/x-archive/managed.md Normal file
View File

@ -0,0 +1,13 @@
---
title: Managed hosting
---
The Co-op Cloud is still [alpha quality software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha) but you can still work with a co-operative or tech collective to host some part or all of your online digital services with it. Organisations who want to support the project can get in touch with Co-op Cloud service providers via the following list for a quote on what they're looking for and how much it will cost. Service providers can then factor in some percentage of the cost to co-fund the development of this project.
!!! danger "We're still working this out"
If you're a co-operative or a tech collective who wants to appear on this list, please [get in touch](/contact/)! We want to expand the number of service providers using the Co-op Cloud so that project is more widely available to end-users and organisations who can influence the direction and co-fund the development.
## Co-operatives
- [Autonomic](https://autonomic.zone) ([contact](mailto:helo@autonomic.zone))

21
docs/x-archive/networking.md Normal file
View File

@ -0,0 +1,21 @@
---
title: Docker Networking
---
!!! warning
Our understanding of Docker networking is probably wrong. We're working on it.
# Traefik networking
When a new Co-op Cloud instance is made, we make a "global" [overlay network](https://docs.docker.com/network/overlay/) which traefik sits on. This is the network that other apps use to speak to traefik and get traffic routed to them. Not every service in every app is also included in this network and hence not internet-facing.
# App networking
One service in an app, typically the one called `app`, sits on the "global" traefik network. This container is the one that should be publicy reachable on the internet. The other services in the app such as the database and caches should be not be publicly reachable or visible to other apps on the same instance.
To deal with this, we make an additional "internal" network for each app which is namespaced to that app. So, if you deploy a Wordpress instance called `my_wordpress_blog` then there will be a network called `my_wordpress_blog_internal` created. This allows all the services in an app to speak to each other but not be reachable on the public internet.
# Avoiding namespace conflicts
When referencing an `app` service in a config file, you should prefix with the `STACK_NAME` to avoid namespace conflicts (because all these containers sit on the traefik overlay network). You might want to do something like this `{{ env "STACK_NAME" }}_app` (using Golang templating).

64
docs/x-archive/overview.md Normal file
View File

@ -0,0 +1,64 @@
---
title: Technical overview
---
The Co-op Cloud is made up of a few simple, composable pieces. The system does not rely on any one specific implementation: each part may be replaced and extended as needed.
- [Libre software apps](#libre-software-apps)
- [The packaging format](#the-packaging-format)
- [Container orchestrator](#container-orchestrator)
- [Command-line tool](#command-line-tool)
## Libre software apps
Applications that you may already use in your daily life: [Nextcloud], [Jitsi], [Mediawiki], [Rocket.chat] and [many more]! These are tools that are created by volunteer communities who use [free software licenses] in order to build up the public software commons and offer more digital alternatives.
The communities who develop these softwares also publish them using containers. For example, here is the [Nextcloud hub.docker.com account] which allows end-users to quickly deploy a new Nextcloud instance.
Learn more about why we use containers [in the FAQ section](/faq/#why-containers).
[nextcloud]: https://nextcloud.com
[jitsi]: https://jitsi.org
[mediawiki]: https://mediawiki.org
[rocket.chat]: https://rocket.chat
[many more]: /apps/
[free software licenses]: https://www.gnu.org/philosophy/free-sw.html
[nextcloud hub.docker.com account]: https://hub.docker.com/_/nextcloud
## The packaging format
The work required to take a new instance of an application and make it production ready is still too time intensive and often involves a duplication of effort. Each service provider needs to deal with the same problems: stable versioning, backup plan, secret management, upgrade plan, monitoring and the list goes on.
Therefore, the Co-op Cloud proposes a packaging format which describes the entire production state of the application in a single place. This format uses the existing [standards based compose specification]. This is a file format which is most commonly used by the [Docker compose] tool but Co-op Cloud **does not** require the use of Docker compose itself.
[Each application] that the Co-op cloud provides is described using the compose specification and makes use of the upstream project published container.
Learn more about why we use the compose specification [in the FAQ section](/faq/#why-use-the-compose-specification).
[standards based compose specification]: https://compose-spec.io
[docker compose]: https://docs.docker.com/compose/
[each application]: /apps/
## Container orchestrator
Once we have our application packaged, we need a deployment environment. Production deployments are typically expected to support a number of features which give hosters and end-users guarantees for uptime, stability and scale.
The Co-op cloud makes use of [Docker swarm] as a deployment environment. It offers an approriate feature set which allows us to support zero-down time upgrades, seamless application rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design.
Learn more about why we use Docker swarm [in the FAQ section](/faq/#why-docker-swarm).
[docker swarm]: https://docs.docker.com/engine/swarm/
## 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]: https://git.autonomic.zone/coop-cloud/abra
## Next steps
Now that you've got an overview, it is time to [deploy your first application].
[deploy your first application]: /deploy/

106
docs/x-archive/recipe-maintainer-guide.md Normal file
View File

@ -0,0 +1,106 @@
---
title: Recipe maintainer guide
---
## Package your first recipe
Let's take as an example, [Matomo web analytics](https://matomo.org/).
We'll be making a Docker "swarm-mode" `compose.yml` file.
- Tired: Write your own image and compose file
- Wired: Use someone else's image (& maybe compose file)
- Inspired: Upstream image, someone else's compose file
- On fire: Upstream compose file
I'm feeling lazy so, luckily for me, Matomo already has an example compose file in their repository.
Like a lot of compose files, it's intended for use with `docker-compose`, instead of "swarm mode", but it should be a good start.
First, let's create a directory with the files we need:
```
abra recipe new matomo
cd ~/.abra/apps/matomo
```
Then, let's download and edit the `docker-compose.yml` file:
```
mkdir matomo && cd matomo
wget https://raw.githubusercontent.com/matomo-org/docker/master/.examples/apache/docker-compose.yml -O compose.yml
```
Open the `compose.yml` in your favourite editor and have a gander &#129442;. There are a few things we're looking for -- full list to come -- but some immediate changes could be:
1. Let's bump the version to `3.8`, to make sure we can use all the latest swarm coolness
2. We load environment variables separately via [abra](/overview/#command-line-tool), so we'll strip out `env_file`.
3. The `/var/www/html` volume definition on L21 is a bit overzealous; it means a copy of Matomo will be stored separately per app instance, which is a waste of space in most cases. We'll narrow it down according to the documentation -- here, the developers have been nice enough to suggest `logs` and `config` volumes instead, which is a decent start
4. The MySQL passwords are sent as variables which is fine for basic use, but if we replace them with Docker secrets we can keep them out of our env files if we want to publish those more widely.
5. The MariaDB service doesn't need to be exposed to the internet, so we can define an `internal` network for it to communicate with Matomo.
6. Lastly, we want to use `deploy.labels` and remove the `ports:` definition, to tell Traefik to forward requests to Matomo based on hostname and generate an SSL certificate.
The resulting `compose.yml` is available [here](https://git.autonomic.zone/coop-cloud/matomo/src/branch/main/compose.yml).
!!! note "Running Co-op Cloud server required!"
The rest of this guide assumes you have a Co-op Cloud server going -- we'll use `swarm.example.com`, but replace it with your own server address.
Head over to [the deployment guide](./deploy.md) if you need help setting one up.
Now, we're ready to create a testing instance of Matomo:
```
abra app new matomo --secrets \
--domain matomo.swarm.example.com \
--server swarm.example.com \
--app-name mygreatapp
```
Depending on whether you defined any extra environment variables -- we didn't so
far, in this example -- you might want to run `abra app mygreatapp config` to
check the configuration.
Otherwise, or once you've done that, go ahead and deploy the app:
```
abra app mygreatapp deploy
```
Then, open the `DOMAIN` you configured (you might need to wait a while for Traefik to generate SSL certificates) to finish the set-up. Luckily, this container is (mostly) configurable via environment variables -- if we want to auto-generate the configuration we can use a `config` and / or a custom `entrypoint` (see [`coop-cloud/mediawiki`](https://git.autonomic.zone/coop-cloud/mediawiki) for examples of both).
## How recipes are versioned
> We are still working on stabilising this workflow
We'll use an example to work through this. Let's use [Gitea](https://hub.docker.com/r/gitea/gitea).
The Gitea project maintains a version, e.g. `1.14.3`. This version uses the [semver](https://semver.org) strategy for communicating what type of changes are included in each version, i.e., if there is a breaking change, Gitea will release a new version as `2.0.0`.
However, there are other types of changes that can happen for a recipe. Perhaps the database image gets a breaking update or the actual recipe configuration changes some environment variable. This can mean that end-users of the recipe need to do some work to make sure their updates will deploy successfully.
Therefore, we maintain an additional version part, in front of the project version. So, the first release of the Gitea recipe in the Co-op Cloud project has the version of `1.0.0+1.14.3-rootless`. This `x.y.z+` is the version part that the recipe maintainer manages. If a new available Gitea version comes out as `1.15-rootless` then the recipe maintainer will publish `1.1.0+1.15-rootless` as this is a backwards compatible update, following semantic versioning.
In all cases, we follow the semver semantics. So, if we upgrade the Gitea recipe from `1.14.3-rootless` to `1.15.3-rootless`, we still publish `1.1.0+1.15.3-rootless` as our recipe version. In this case, we skipped a few patch releases but it was all backwards compatible, so we only increment the minor version part.
The commands uses for dealing with this logic in `abra` are:
- `abra recipe upgrade`: upgrade the image tags in the compose configs of a recipe
- `abra recipe tag`: publish a git tag for the recipe repo
- `abra recipe sync`: upgrade the deploy labels to match the new recipe version
## How to publish a new recipe version
!!! warning
Due to [a limitation](https://git.coopcloud.tech/coop-cloud/organising/issues/185) in the Git library we're using in `abra`, when tagging new releases, you **must** use annotated git tags (i.e. `git tag -a`) or `abra` won't be able to parse them correctly. On the up side, it is probably better to leave a message with your new Git tag anyway. So maybe this is just "best practice" ;)
> This process is very much still a work in progress...
- `abra recipe upgrade keycloak`
- `abra recipe sync keycloak "1.0.0+13.0.1"`
- `abra recipe release -c --cm "chore: first release" -t "first release" --push`
## Style guide
- Please don't use `&image` YAML repeat anchors on the `image: ...` key because our `recipe release` logic does not handle it (see [#172](https://git.autonomic.zone/coop-cloud/abra/issues/172))

50
docs/x-archive/recipe-structure.md Normal file
View File

@ -0,0 +1,50 @@
---
title: Recipe structure
---
A recipe is a git repository that contains instructions for creating stacks that abra can read and interpret. You'll see a couple of files there:
- [compose.yml](#composeyml) (required!)
- [.env.sample](#envsample) (required!)
- [abra.sh](#abrash)
- [entrypoint.sh](#entrypointsh)
- [other compose files](#other-compose-files)
- [other files](#other-files)
## compose.yml
this is a [compose specification](https://compose-spec.io/) compliant file that contains a list of:
- services
- secrets
- networks
- volumes
- configs
that describe what is needed to run a stack. Whenever you deploy an app, abra reads this file to cook the stack.
## .env.sample
this file is a skeleton for environmental variables that should be adjusted by the user. Examples include: domain or php extention list. Whenever you create a new app with `abra app new` this file gets copied to the ~/.abra/servers/server-domain/app-name.env and when you run `abra app config` you're editing this file.
## abra.sh
`abra.sh` provides shell functions for running non-standard deploy, restore, rollback, backup and upgrade. This is only needed for some packages (such as nextcloud or wordpress)
## entrypoint.sh
after docker creates the filesystem and copies files into a new container it runs what's called an entrypoint. This is usually a shell script that exports some variables and runs the application. Sometimes the vendor entrypoint doesn't do everything that we need it to do. In that case you can write your own entrypoint, do whatever you need to do and then run the vendor entrypoint. For a simple example check [entrypoint.sh for croc](https://git.coopcloud.tech/coop-cloud/croc/src/commit/2f06e8aac52a3850d527434a26de0a242bea0c79/entrypoint.sh). In this case, croc needs the password to be exported as an environmental variable called `CROC_PASS`, and that is exactly what the entrypoint does before running vendor entrypoint. If you write your own entrypoint, it needs to be specified in the `config` section of compose.yml.
## other compose files
i.e. compose.smtp.yml. These are used to provide non-essential functionality such as (registration) e-mails or single sign on.
## other files
if you look at compose.yml (or compose.\*.yml) and see a `configs` section, that means this compose file is putting files in the container. This might be used for changing default (vendor) configuration, such as this [fpm-tune.ini file](https://git.coopcloud.tech/coop-cloud/nextcloud/src/commit/28425b6138603067021757de28c639ad464e9cf8/fpm-tune.ini) used to adjust php-fpm.

5
docs/x-archive/rollback.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Roll an app back to a previous version
---
TODO.

5
docs/x-archive/scale.md Normal file
View File

@ -0,0 +1,5 @@
---
title: Scale an app up to handle more traffic
---
TODO.

109
docs/x-archive/secrets.md Normal file
View File

@ -0,0 +1,109 @@
---
title: Managing secret data
---
# Managing secret data
Co-op Cloud uses [Docker Secrets] to handle sensitive data, like database passwords and API keys, securely:
```
DOCKER_CONTEXT=swarm.example.com docker secret ls
example_mediawiki_db_password_v1
example_wordpress_db_password_v1
```
`abra` includes several commands to make it easier to manage secrets:
- `abra app <app> secret generate` -- to auto-generate a single secret, or all secrets defined by the app, and store them in the Docker Swarm store,
- `abra app <app> secret insert` -- to insert a single secret value from the Docker Swarm store,
- `abra app <app> secret delete` -- to remove a single secret, or all secrets defined in the app, from the Docker Swarm store.
<a id="versions"></a>
## Secret versions
You will notice `v1` in the example secret names above: like Docker Configs, Docker Secrets are [immutable], which means that their values can't be changed after they're set. To accommodate this, Co-op Cloud uses the established convention of "secret versions". Every time you change (rotate) a secret, you will insert it as a new version.
Because secret versions are managed per-instance by the people deploying their apps, secret versions are stored in the `.env` file for each app:
```
find -L ~/.abra/servers/ -name '*.env' -print0 | xargs -0 grep -h SECRET
OIDC_CLIENT_SECRET_VERSION=v1
RPC_SECRET_VERSION=v1
CLIENT_SECRET_VERSION=v1
...
```
If you try and add a secret version which already exists, Docker will helpfully complain:
```
abra app example_wordpress secret insert db_password v1 foobar
Error response from daemon: rpc error: code = AlreadyExists desc = secret example_wordpress_db_password_v1 already exists
```
By default, new app instances will look for `v1` secrets.
## Generating secrets automatically
You can generate secrets in one of two ways:
1. While running `abra app new <type>`, by passing `--secrets`
2. At any point once an app instance is defined, by running `abra app <app> secret generate ...` (see `abra help secret generate` for full options)
!!! note "How are secrets generated?"
Depending on how the app is configured, you will require the `pwqgen` (from `passwdqc`) and `pwgen` binaries by default, although you can specify your own password-generation app when running `abra <app> secret generate` by providing the `<cmd>` argument.
## Inserting secrets manually
For third-party API tokens, like OAuth client secrets, or keys for services like Mailgun, you will be storing values you already have as the appropriately-named Docker secrets. `abra` provides a convenient interface to the underlying `docker secret create` command:
```
abra app example_wordpress secret insert db_password v2 "your-secret-here"
```
## Rotating a secret
So, given how [secret versions](#versions) work, here's how you change a secret:
1. Find out the current version number of the secret, e.g. by running `abra app example_wordpress config`, and choose a new one. Let's assume it's currently `v1`, so by convention the new secret will be `v2`.
2. Generate or insert the new secret:
```
abra app example_wordpress secret generate db_password v2
```
or
```
abra app example_wordpress secret insert db_password v2 "foobar"
```
3. Edit the app configuration to change which secret version the app will use:
```
abra app example_wordpress config
```
4. Re-reploy the app with the new secret version:
```
abra app example_wordpress deploy
```
## Storing secrets in `pass`
The Co-op Cloud authors use the [UNIX `pass` tool][pass] to share sensitive data, including Co-op Cloud secrets, and `abra <app> secret...` commands include a `--pass` option to automatically manage generated / inserted secrets:
```
# Store generated secrets in `pass`:
abra app new wordpress --secrets --pass
abra app example_wordpress secret generate --all --pass
# Store inserted secret in `pass`:
abra app example_wordpress secret insert db_password v2 --pass
# Remove secrets from Docker, and `pass`:
abra app example_wordpress secret rm --all --pass
```
This functionality currently relies on our specific `pass` structure; patches to make that configurable are very welcome!
## What makes secrets secure?
TODO
[docker secrets]: https://docs.docker.com/engine/swarm/secrets/
[immutable]: https://en.wikipedia.org/wiki/Immutable_object
[pass]: https://www.passwordstore.org

24
docs/x-archive/server-side.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Running abra on the server
---
## Why?
If you're on an environment where it's hard to run Docker, or command-line programs in general, you might want to install `abra` on a server instead of your local computer.
To install `abra` on a different server than you'll be hosting your apps, just follow [getting started guide](/overview/) as normal.
If you want to install `abra` on the same server, there's one change.
Instead of providing your SSH connection details when you run `abra server add ...`, just use `default`:
```
abra server add default
```
!!! note "Technical details"
This will tell `abra` to look at the Docker system running on the server, instead of a remote one.
Make sure to back up your `~/abra/` directory on the server, or put it in version control, as well as other files you'd like to.

33
docs/x-archive/strategy.md Normal file
View File

@ -0,0 +1,33 @@
---
title: Project strategy
---
## What are the goals of the Co-op Cloud?
!!! note "Yes, we do have a blog"
Some leading thoughts are outlined in the [project launch blog post](https://autonomic.zone/blog/co-op-cloud/) also.
From our experiences working and organising as Autonomic, the tech co-op who initiated Co-op Cloud, we know that the progressive tech movement lack reliable and cost-effective technical means for providing an alternative to “Big Tech” cloud services.
The urgency for providing an alternative comes out of the understanding that the concentration of our digital lives within the private sphere of corporate providers (e.g. [GAFAM](https://degooglisons-internet.org/en/)) represents a loss of freedom due to the threat to our privacy and self-determination through surveillance and monopolisation.
As a movement, we cannot compete with corporate providers in terms of cost and scale. Their network effects and available capital means that no one project, product or organisation can create the required shift to a more widespread public interest technology.
Our strategy is to mutualise our resources to create this shift. Co-op Cloud is an attempt to create a new shared resource - an open and democratically managed, open standards based, copyleft licensed, libre software infrastructure project.
## Compensation for contributions
We think that it is important to focus on making the libre software ecosystem sustainable. This has historically [not been the case](https://www.fordfoundation.org/media/2976/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure.pdf).
It feels important to contextualise this position. In the words of [LURK](https://lurk.org):
> Big tech and an abusive misunderstanding of free and open source software practices have led us to believe that software production, server maintenance and on-line services should be free as in gratis. However there is no such things as a free lunch and software does not exist in a vacuum. If we want sustainable alternatives and a diverse cultural sector, these alternatives and the humans behind them, need to be supported.
And a short excerpt from [Seven Theses On The Fediverse and The Becoming Of FLOSS](https://archive.transmediale.de/content/seven-theses-on-the-fediverse-and-the-becoming-of-floss):
> Without substantial funding for ongoing development and maintenance, these projects will remain contingent upon the exploitation of the free labor of well-meaning individuals, or subject to the whims of people making time for their FLOSS hobby.
We want to build a flourishing, inclusive, accessible project and paying people for their work (not just writing source code, but other forms of organising and care work too!) has a role to play in that. We think that making it possible to compensate contributors for working on Co-op Cloud is a way to get involved with self-organising sustainability from the start.
We haven't worked this all out. We've opened up an [Open Collective account](https://opencollective/coop-cloud) and we're running this as an "invite only mode" approach. **If you want to make a contribution to Co-op Cloud and you'd like to be compensated, please [come and chat to us first](https://docs.coopcloud.tech/contact/).**

35
docs/x-archive/troubleshooting.md Normal file
View File

@ -0,0 +1,35 @@
---
title: Troubleshooting
---
## SSH / connection problems
Assuming:
- Hostname: `coopcloud.example.com`
- User: `username`
- Port: `222`
### Step 1: Can you SSH to the server normally?
Does `ssh username@coopcloud.example.com -p2222` work?
If not, run through your standard oh-no-why-doesn't-SSH-work troubleshooting 🍀.
### Step 2: Can you run remote Docker commands over SSH?
Does `ssh username@coopcloud.example.com -p2222 docker ps` work?
If not:
- Is the remote Docker daemon running?
- Is your user in the `docker` group?
### Step 3: Does your Docker context work?
```
[user@hostname ~]$ DOCKER_CONTEXT=coopcloud.example.com docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```
If you get an error message instead:
- Use `abra server ls` / `docker context ls` to double-check the SSH connection details
- Try removing the context with `docker context rm coopcloud.example.com`, then re-add it