From 43211efebdb9e9540a8ab51ffc4672fcc8d86927 Mon Sep 17 00:00:00 2001 From: basebuilder Date: Mon, 5 Feb 2024 19:54:48 +0100 Subject: [PATCH 01/16] renamed Federation: FAQ to Bylaws; added intro sentence --- docs/federation/{faq.md => bylaws.md} | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) rename docs/federation/{faq.md => bylaws.md} (83%) diff --git a/docs/federation/faq.md b/docs/federation/bylaws.md similarity index 83% rename from docs/federation/faq.md rename to docs/federation/bylaws.md index 4a83164..f16b8ee 100644 --- a/docs/federation/faq.md +++ b/docs/federation/bylaws.md @@ -1,7 +1,10 @@ --- -title: FAQ +title: Bylaws --- +The following are the bylaws which the _Co-op Cloud: Federation_ has decided +democratically and layout our governance processes :classical_building: :fist: + ## What is the Co-op Cloud Federation? > We're still working things out, here's what know so far! From 99a31ac3b734fbf94de09bae45772393cf1c20ab Mon Sep 17 00:00:00 2001 From: basebuilder Date: Mon, 5 Feb 2024 19:56:15 +0100 Subject: [PATCH 02/16] Remove undeed Resolutions index.md files, adjst Template --- docs/federation/resolutions/drafts/index.md | 3 --- docs/federation/resolutions/in-progress/index.md | 3 --- docs/federation/resolutions/index.md | 14 ++++++++++---- mkdocs.yml | 13 ++++++------- 4 files changed, 16 insertions(+), 17 deletions(-) delete mode 100644 docs/federation/resolutions/drafts/index.md delete mode 100644 docs/federation/resolutions/in-progress/index.md diff --git a/docs/federation/resolutions/drafts/index.md b/docs/federation/resolutions/drafts/index.md deleted file mode 100644 index c4684c1..0000000 --- a/docs/federation/resolutions/drafts/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Drafts ---- diff --git a/docs/federation/resolutions/in-progress/index.md b/docs/federation/resolutions/in-progress/index.md deleted file mode 100644 index 78d3283..0000000 --- a/docs/federation/resolutions/in-progress/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: In progress ---- diff --git a/docs/federation/resolutions/index.md b/docs/federation/resolutions/index.md index 99a3b9c..99c7ba6 100644 --- a/docs/federation/resolutions/index.md +++ b/docs/federation/resolutions/index.md @@ -4,15 +4,21 @@ title: Resolutions ### Resolution Template -```javascript -## Resolution : - <date> +``` yaml +--- +title: Resolution <number> +--- +- Topic: <title> +- Date: 13-12-2023 - Deadline: Date - Size: large or medium ### Summary -Who this affects, and what it does + +Who this affects, and what it does... ### Details -A narrative with details + +A narrative with details... ``` diff --git a/mkdocs.yml b/mkdocs.yml index 1d2d58a..8da7ba6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ markdown_extensions: - pymdownx.magiclink - pymdownx.mark - pymdownx.smartsymbols + - pymdownx.snippets - pymdownx.superfences - pymdownx.tabbed - pymdownx.tilde @@ -93,7 +94,9 @@ nav: - get-involved/index.md - "Federation": - federation/index.md - - "FAQ": federation/faq.md + - "Bylaws": federation/bylaws.md + - "Finance": federation/finance.md + - "Membership": federation/membership.md - "Resolutions": - federation/resolutions/index.md - "Passed": @@ -111,20 +114,16 @@ nav: - federation/resolutions/passed/012.md - federation/resolutions/passed/014.md - federation/resolutions/passed/015.md - - "In progress": - - federation/resolutions/in-progress/index.md + - "In Progress": - federation/resolutions/in-progress/016.md - federation/resolutions/in-progress/017.md - "Draft": - - federation/resolutions/drafts/index.md - federation/resolutions/drafts/013.md - - "Finance": federation/finance.md - - "Membership": federation/membership.md - "Minutes": - federation/minutes/index.md - "2022": - federation/minutes/2022-03-03.md - - "Digital tools": federation/tools.md + - "Digital Tools": federation/tools.md - "Glossary": - glossary/index.md From 05f12b7555b37241c9a0a5437260d433051d10d2 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Mon, 5 Feb 2024 19:57:18 +0100 Subject: [PATCH 03/16] Tidy up titles of Resolutions into unique lines of content --- docs/federation/resolutions/drafts/013.md | 4 +++- docs/federation/resolutions/in-progress/016.md | 4 +++- docs/federation/resolutions/in-progress/017.md | 4 +++- docs/federation/resolutions/passed/001.md | 4 +++- docs/federation/resolutions/passed/002.md | 4 +++- docs/federation/resolutions/passed/003.md | 4 +++- docs/federation/resolutions/passed/004.md | 4 +++- docs/federation/resolutions/passed/005.md | 4 +++- docs/federation/resolutions/passed/006.md | 6 +++--- docs/federation/resolutions/passed/007.md | 4 +++- docs/federation/resolutions/passed/008.md | 4 +++- docs/federation/resolutions/passed/009.md | 6 +++--- docs/federation/resolutions/passed/010.md | 6 +++--- docs/federation/resolutions/passed/011.md | 4 +++- docs/federation/resolutions/passed/012.md | 4 +++- docs/federation/resolutions/passed/014.md | 4 +++- docs/federation/resolutions/passed/015.md | 4 +++- 17 files changed, 51 insertions(+), 23 deletions(-) diff --git a/docs/federation/resolutions/drafts/013.md b/docs/federation/resolutions/drafts/013.md index f02dc5c..3bfbc27 100644 --- a/docs/federation/resolutions/drafts/013.md +++ b/docs/federation/resolutions/drafts/013.md @@ -1,5 +1,5 @@ --- -title: "Resolution 013: Budget 007: Operator sync - 2024-01-??" +title: "Resolution 013" --- !!! note @@ -8,6 +8,8 @@ title: "Resolution 013: Budget 007: Operator sync - 2024-01-??" git synchronisation; please see [the file history](https://git.coopcloud.tech/coop-cloud/docs.coopcloud.tech/commits/branch/main/docs/federation/resolutions/in-progress/013.md) for a full run-down. +- Budget 007: Operator sync +- Date: 2024-01-?? - Deadline: 2024-01-XX - Size: Large diff --git a/docs/federation/resolutions/in-progress/016.md b/docs/federation/resolutions/in-progress/016.md index 8b404b8..7776bb8 100644 --- a/docs/federation/resolutions/in-progress/016.md +++ b/docs/federation/resolutions/in-progress/016.md @@ -1,7 +1,9 @@ --- -title: "Resolution 016: Budget 008: Backup-bot-two Documentation and Specification - 27-01-2024" +title: "Resolution 016" --- +- Topic: Budget 008: Backup-bot-two Documentation and Specification +- Date: 27-01-2024 - Deadline: 10th February 2024 - Size: Large diff --git a/docs/federation/resolutions/in-progress/017.md b/docs/federation/resolutions/in-progress/017.md index c4dbfd8..77cf406 100644 --- a/docs/federation/resolutions/in-progress/017.md +++ b/docs/federation/resolutions/in-progress/017.md @@ -1,7 +1,9 @@ --- -title: "Resolution 17: BeWater joins the Co-op Cloud Federation - 30-01-2024" +title: "Resolution 017" --- +- Topic: BeWater joins the Co-op Cloud Federation +- Date: 30-01-2024 - Deadline: 13-02-2024 - Size: Large diff --git a/docs/federation/resolutions/passed/001.md b/docs/federation/resolutions/passed/001.md index 7cffb7b..224a6fb 100644 --- a/docs/federation/resolutions/passed/001.md +++ b/docs/federation/resolutions/passed/001.md @@ -1,7 +1,9 @@ --- -title: "Proposal 001: Decision Making Process - 2023-03-03" +title: "Resolution 001" --- +- Topic: Decision Making Process +- Date: 2023-03-03 - Deadline: 2023-03-03 (live voting) - Size: large diff --git a/docs/federation/resolutions/passed/002.md b/docs/federation/resolutions/passed/002.md index cae8124..2d57c41 100644 --- a/docs/federation/resolutions/passed/002.md +++ b/docs/federation/resolutions/passed/002.md @@ -1,7 +1,9 @@ --- -title: "Resolution 002: Membership/Dues - 2023-03-22" +title: "Resolution 002" --- +* Topic: Membership/Dues +* Date: 2023-03-22 * Deadline: 2023-04-11 * Passed on 2023-04-13 * Size: Large diff --git a/docs/federation/resolutions/passed/003.md b/docs/federation/resolutions/passed/003.md index 429b850..70dbf7c 100644 --- a/docs/federation/resolutions/passed/003.md +++ b/docs/federation/resolutions/passed/003.md @@ -1,7 +1,9 @@ --- -title: "Resolution 003: Paid work - 2023-03-22" +title: "Resolution 003" --- +* Topic: Paid work +* Date: 2023-03-22 * Deadline: 2023-04-11 * Passed on 2023-04-13 * Size: Large diff --git a/docs/federation/resolutions/passed/004.md b/docs/federation/resolutions/passed/004.md index 4b10f13..a76a8c0 100644 --- a/docs/federation/resolutions/passed/004.md +++ b/docs/federation/resolutions/passed/004.md @@ -1,7 +1,9 @@ --- -title: "Resolution 004: Budget 001: Budgeting - 2023-03-22" +title: "Resolution 004" --- +* Topic: Budget 001: Budgeting +* Date: 2023-03-22 * Deadline: 2023-04-11 * Passed on 2023-04-13 * Size: Large diff --git a/docs/federation/resolutions/passed/005.md b/docs/federation/resolutions/passed/005.md index 3a3f458..15ec762 100644 --- a/docs/federation/resolutions/passed/005.md +++ b/docs/federation/resolutions/passed/005.md @@ -1,7 +1,9 @@ --- -title: "Resolution 005: Public federation membership, notes and decisions - 2023-04-14" +title: "Resolution 005" --- +* Topic: Public federation membership, notes and decisions +* Date: 2023-04-14 * Deadline: 2023-04-17 * Passed: 2023-04-18 * Size: medium diff --git a/docs/federation/resolutions/passed/006.md b/docs/federation/resolutions/passed/006.md index f1beb8f..2e8fd00 100644 --- a/docs/federation/resolutions/passed/006.md +++ b/docs/federation/resolutions/passed/006.md @@ -1,9 +1,9 @@ --- -title: "Resolution 006: Budget 002: Resolution Writing-up - 2023-05-29" +title: "Resolution 006" --- -# Resolution 006: Budget 002: Resolution Writing-up - 2023-05-29 - +- Budget 002: Resolution Writing-up +- Date: 2023-05-29 - Deadline: 2022-06-12 - Size: Large diff --git a/docs/federation/resolutions/passed/007.md b/docs/federation/resolutions/passed/007.md index 87528f1..ff0e56f 100644 --- a/docs/federation/resolutions/passed/007.md +++ b/docs/federation/resolutions/passed/007.md @@ -1,7 +1,9 @@ --- -title: "Resolution 007: 1 year dues waiver for Doop.coop - 2023-06-19" +title: "Resolution 007" --- +- Topic: 1 year dues waiver for Doop.coop +- Date: 2023-06-19 - Deadline: 2023-07-03 - Size: Medium diff --git a/docs/federation/resolutions/passed/008.md b/docs/federation/resolutions/passed/008.md index 9797982..345088a 100644 --- a/docs/federation/resolutions/passed/008.md +++ b/docs/federation/resolutions/passed/008.md @@ -1,7 +1,9 @@ --- -title: "Resolution 008: Budget 003: Paying invoices - 2023-06-19" +title: "Resolution 008" --- +- Topic: Budget 003 Paying invoices +- Date: 2023-06-19 - Deadline: 2022-07-03 - Size: Large diff --git a/docs/federation/resolutions/passed/009.md b/docs/federation/resolutions/passed/009.md index 12daa50..eaa2ed4 100644 --- a/docs/federation/resolutions/passed/009.md +++ b/docs/federation/resolutions/passed/009.md @@ -1,9 +1,9 @@ --- -title: "Resolution 009: Federation common fund buffer - 2023-07-03" +title: "Resolution 009" --- -## Resolution 009: Federation common fund buffer - 2023-07-03 - +- Topic: Federation common fund buffer +- Date: 2023-07-03 - Deadline: 2023-07-17 - Size: Large diff --git a/docs/federation/resolutions/passed/010.md b/docs/federation/resolutions/passed/010.md index 21acecf..330d462 100644 --- a/docs/federation/resolutions/passed/010.md +++ b/docs/federation/resolutions/passed/010.md @@ -1,9 +1,9 @@ --- -title: "Resolution 010: Budget 004: Critical fixes - 2023-07-03" +title: "Resolution 010" --- -## Resolution 010: Budget 004: Critical fixes - 2023-07-03 - +- Topic: Budget 004: Critical fixes +- Date: 2023-07-03 - Deadline: 2023-07-17 - Size: Large diff --git a/docs/federation/resolutions/passed/011.md b/docs/federation/resolutions/passed/011.md index 168d59d..b7e527f 100644 --- a/docs/federation/resolutions/passed/011.md +++ b/docs/federation/resolutions/passed/011.md @@ -1,7 +1,9 @@ --- -title: "Resolution 011: Budget 005: Backup improvements - 2023-07-23" +title: "Resolution 011" --- +- Topic: Budget 005: Backup improvements +- Date: 2023-07-23 - Deadline: 2022-08-06 - Size: Large diff --git a/docs/federation/resolutions/passed/012.md b/docs/federation/resolutions/passed/012.md index 55fda3b..6c404b8 100644 --- a/docs/federation/resolutions/passed/012.md +++ b/docs/federation/resolutions/passed/012.md @@ -1,7 +1,9 @@ --- -title: "Resolution 012: Budget 006: Abra integration test suite - 2023-09-09" +title: "Resolution 012" --- +- Budget 006: Abra integration test suite +- Date: 2023-09-09 - Deadline: 2023-09-23 - Size: Large diff --git a/docs/federation/resolutions/passed/014.md b/docs/federation/resolutions/passed/014.md index afcef83..709b213 100644 --- a/docs/federation/resolutions/passed/014.md +++ b/docs/federation/resolutions/passed/014.md @@ -1,7 +1,9 @@ --- -title: "Resolution 014: Budget 008: Critical Fixes - 2023-12-06" +title: "Resolution 014" --- +- Topic: Budget 008: Critical Fixes +- Date: 2023-12-06 - Deadline: 2023-12-24 - Size: Large diff --git a/docs/federation/resolutions/passed/015.md b/docs/federation/resolutions/passed/015.md index 3beac97..7ee2ebf 100644 --- a/docs/federation/resolutions/passed/015.md +++ b/docs/federation/resolutions/passed/015.md @@ -1,7 +1,9 @@ --- -title: "Resolution 15: Klasse & Methode joins the Co-op Cloud Federation - 25-01-2024" +title: "Resolution 015" --- +- Topic: Klasse & Methode joins the Co-op Cloud Federation +- Date: 25-01-2024 - Deadline: 08-02-2024 - Size: Large From 4960b301e079485dd9d45f963a46fdfd1dc3e953 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Mon, 12 Feb 2024 12:09:56 +0100 Subject: [PATCH 04/16] Add first pass of a Support Us page --- docs/get-involved/support.md | 25 +++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 26 insertions(+) create mode 100644 docs/get-involved/support.md diff --git a/docs/get-involved/support.md b/docs/get-involved/support.md new file mode 100644 index 0000000..08a8d54 --- /dev/null +++ b/docs/get-involved/support.md @@ -0,0 +1,25 @@ +--- +title: "Support Us" +--- + +If you like what you see whilst browsing Co-op Cloud and would like to +contribute financially, as opposed to with code, we currently receive donations +via an [Open Collective account](https://opencollective.com/coop-cloud). + +<div class="grid cards" markdown> + +- __Infrastructure Support__ + + If you make use of our digital infrastructure and want to help out with + maintenance costs, we wold be grateful :heart: + + [Donate Now](https://opencollective.com/coop-cloud/contribute/infrastructure-sustainability-29878/checkout){ .md-button .md-button--primary } + +- __Joining Federation__ + + If you want to be more actively involved as a supporter, consider joining + our Federation :handshake_tone2: + + [Learn More](/federation/){ .md-button .md-button--primary } + +</div> diff --git a/mkdocs.yml b/mkdocs.yml index fa26c39..6ea1ca1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -91,6 +91,7 @@ nav: - "Cheat Sheet": abra/cheat-sheet.md - "Get Involved": - get-involved/index.md + - "Support Us": get-involved/support.md - "Federation": - federation/index.md - "FAQ": federation/faq.md From 3ae0ac10b3af8ea9c175125967fc3c85da88af54 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Tue, 13 Feb 2024 23:21:27 +0100 Subject: [PATCH 05/16] fix Join The Federation on Support Us page --- docs/get-involved/support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-involved/support.md b/docs/get-involved/support.md index 08a8d54..69d3dbb 100644 --- a/docs/get-involved/support.md +++ b/docs/get-involved/support.md @@ -15,7 +15,7 @@ via an [Open Collective account](https://opencollective.com/coop-cloud). [Donate Now](https://opencollective.com/coop-cloud/contribute/infrastructure-sustainability-29878/checkout){ .md-button .md-button--primary } -- __Joining Federation__ +- __Join The Federation__ If you want to be more actively involved as a supporter, consider joining our Federation :handshake_tone2: From 1172da919cd3de0890d2a687b45fb12cbce62d14 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 14 Feb 2024 10:05:10 +0100 Subject: [PATCH 06/16] add emoji sprinkles to Maintainers Handbook :) --- docs/maintainers/tutorial.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/maintainers/tutorial.md b/docs/maintainers/tutorial.md index 15357dc..d0c08de 100644 --- a/docs/maintainers/tutorial.md +++ b/docs/maintainers/tutorial.md @@ -16,10 +16,10 @@ Depending on your familiarity with recipes, it might be worth reading [how a rec The ideal scenario is when the upstream project provides both the packaged image and a compose configuration which we can build from. If you're in luck, you'll typically find a `Dockerfile` and a `docker-compose.yml` file in the root of the upstream Git repository for the app. -- **Tired**: Write your own image and compose file from scratch -- **Wired**: Use someone else's image (& maybe compose file) -- **Inspired**: Upstream image, someone else's compose file -- **On fire**: Upstream image, upstream compose file +- **Tired**: Write your own image and compose file from scratch :sleeping: +- **Wired**: Use someone else's image (& maybe compose file) :smirk_cat: +- **Inspired**: Upstream image, someone else's compose file :exploding_head: +- **On fire**: Upstream image, upstream compose file :fire: ### Writing / adapting the `compose.yml` From d4c39ab0744cdee76aa46b8f14ee487bc72c297f Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 14 Feb 2024 11:26:33 +0100 Subject: [PATCH 07/16] maintainers handbook, fix mispelling --- docs/maintainers/handbook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maintainers/handbook.md b/docs/maintainers/handbook.md index 3832cc8..6409be0 100644 --- a/docs/maintainers/handbook.md +++ b/docs/maintainers/handbook.md @@ -27,7 +27,7 @@ This is a [compose specification](https://compose-spec.io/) compliant file that ### `.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-domain>.env` and when you run `abra app config <app-domain>` you're editing this file. +This file is a skeleton for environmental variables that should be adjusted by the user. Examples include: domain or PHP extension list. Whenever you create a new app with `abra app new` this file gets copied to the `~/.abra/servers/<server-domain>/<app-domain>.env` and when you run `abra app config <app-domain>` you're editing this file. ### `abra.sh` From 8c85a7928d6dbaff69c823a8cccceb876430ebfa Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 21 Feb 2024 15:17:52 +0100 Subject: [PATCH 08/16] move 'What about -> Comparisons page --- docs/intro/comparisons.md | 121 ++++++++++++++++++++++++++++++++++++++ docs/intro/faq.md | 112 ----------------------------------- mkdocs.yml | 1 + 3 files changed, 122 insertions(+), 112 deletions(-) create mode 100644 docs/intro/comparisons.md diff --git a/docs/intro/comparisons.md b/docs/intro/comparisons.md new file mode 100644 index 0000000..34903a8 --- /dev/null +++ b/docs/intro/comparisons.md @@ -0,0 +1,121 @@ +--- +title: Comparisons +--- + +We think it's important to understand that *Co-op Cloud* is more than just +software and technical configurations. It is also a novel organization of *how* +to [create technology socially](https://docs.coopcloud.tech/federation). +However, strictly technically speaking you may be wondering: + +### 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 + +#### Pros + +- πŸ‘ 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. + +#### Cons + +- πŸ‘Ž 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. +- πŸ‘Ž Upstream 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 + +#### Pros + +- πŸ‘ 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) + +#### Cons + +- πŸ‘Ž 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 + +#### Pros + +- πŸ‘ 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. + +#### Cons + +- πŸ‘Ž 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 + +#### Pros + +- πŸ‘ Includes server creation and bootstrapping. + +#### Cons + +- πŸ‘Ž Upstream libre software communities aren't publishing Ansible roles. +- πŸ‘Ž Lots of manual work involved in things like app isolation, backups, updates. + +### Kubernetes + +#### Pros + +- πŸ‘ Helm charts are available for some key apps already. +- πŸ‘ Scale all the things. + +#### Cons + +- πŸ‘Ž Too big -- requires 3rd party tools to run a single-node instance. +- πŸ‘Ž Not suitable for a small to mid size hosting provider. + +### Docker-compose + +#### Pros + +- πŸ‘ Quick to set up and familiar for many developers. + +#### Cons + +- πŸ‘Ž 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) + +#### Pros + +- πŸ‘ Simple - just follow upstream instructions to install and update. + +#### Cons + +- πŸ‘Ž 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. diff --git a/docs/intro/faq.md b/docs/intro/faq.md index fbc17a3..c278fec 100644 --- a/docs/intro/faq.md +++ b/docs/intro/faq.md @@ -40,118 +40,6 @@ Also see our [strategy page](../strategy/). See ["Package your first recipe"](/maintainers/tutorial/#package-your-first-recipe) 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 - -#### Pros - -- πŸ‘ 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. - -#### Cons - -- πŸ‘Ž 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. -- πŸ‘Ž Upstream 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 - -#### Pros - -- πŸ‘ 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) - -#### Cons - -- πŸ‘Ž 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 - -#### Pros - -- πŸ‘ 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. - -#### Cons - -- πŸ‘Ž 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 - -#### Pros - -- πŸ‘ Includes server creation and bootstrapping. - -#### Cons - -- πŸ‘Ž Upstream libre software communities aren't publishing Ansible roles. -- πŸ‘Ž Lots of manual work involved in things like app isolation, backups, updates. - -### Kubernetes - -#### Pros - -- πŸ‘ Helm charts are available for some key apps already. -- πŸ‘ Scale all the things. - -#### Cons - -- πŸ‘Ž Too big -- requires 3rd party tools to run a single-node instance. -- πŸ‘Ž Not suitable for a small to mid size hosting provider. - -### Docker-compose - -#### Pros - -- πŸ‘ Quick to set up and familiar for many developers. - -#### Cons - -- πŸ‘Ž 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) - -#### Pros - -- πŸ‘ Simple - just follow upstream instructions to install and update. - -#### Cons - -- πŸ‘Ž 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? diff --git a/mkdocs.yml b/mkdocs.yml index 6ea1ca1..cda5ac0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ nav: - index.md - "Frequently asked questions": intro/faq.md - "Project strategy": intro/strategy.md + - "Comparisons": intro/comparisons.md - "Project status": intro/bikemap.md - "Managed hosting": intro/managed.md - "Get in touch": intro/contact.md From c3cc6fc1c6dc56013c3a0cce05fc4feb1813d0fa Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 21 Feb 2024 16:10:36 +0100 Subject: [PATCH 09/16] add Stackspin Comparison --- docs/intro/comparisons.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/intro/comparisons.md b/docs/intro/comparisons.md index 34903a8..6fdc807 100644 --- a/docs/intro/comparisons.md +++ b/docs/intro/comparisons.md @@ -119,3 +119,22 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n - πŸ‘Ž 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. + + +### Stackspin + +#### Pros + +- πŸ‘ Easy instructions to install & upgrade multiple tightly integrated apps. +- πŸ‘ Offers a unified SSO user experience. +- πŸ‘ Offers tightly integrated logging, monitoring, and maintenance. +- πŸ‘ Has a strong focus and attention to security. + +#### Cons + +- πŸ‘Ž Upstream libre software communities aren't involved in packaging. +- πŸ‘Ž It is not designed to be a general specification. +- πŸ‘Ž Hard to share configurations into the commons. +- πŸ‘Ž Significantly limited library of eight apps. +- πŸ‘Ž Additional apps are treated as "External Apps" with only OAuth2/OpenID integration. +- πŸ‘Ž Requires a Kubernetes cluster. From 0ddd0bff661edc22ff23deefc5078297d2518033 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 21 Feb 2024 17:00:38 +0100 Subject: [PATCH 10/16] add Maadix to Comparisons page --- docs/intro/comparisons.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/intro/comparisons.md b/docs/intro/comparisons.md index 6fdc807..4d48564 100644 --- a/docs/intro/comparisons.md +++ b/docs/intro/comparisons.md @@ -138,3 +138,21 @@ Here is a short overview of the pros/cons we see, in relation to our goals and n - πŸ‘Ž Significantly limited library of eight apps. - πŸ‘Ž Additional apps are treated as "External Apps" with only OAuth2/OpenID integration. - πŸ‘Ž Requires a Kubernetes cluster. + + +### Maadix + +#### Pros + +- πŸ‘ Nice looking web interface for app, domain & user management. +- πŸ‘ Offers a paid hosting service to get up and running easily. + +#### Cons + +- πŸ‘Ž Upstream libre software communities aren't involved in packaging. +- πŸ‘Ž It is not designed to be a general specification. +- πŸ‘Ž Hard to share configurations into the commons. +- πŸ‘Ž Limited library of apps. +- πŸ‘Ž Uses *OpenNebula*, *Ansible*, and *Puppet* as underlying technologies. +- πŸ‘Ž Appears to be only a team of two people. +- πŸ‘Ž Appears to be inactive on Mastodon and limited GitLab activity. From 655400877a714a8a1f7c977e36f6b5443e8d5a6d Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Mon, 5 Feb 2024 20:23:00 +0100 Subject: [PATCH 11/16] migrate The Moving Parts into Intro area, stylize --- docs/abra/quickstart.md | 12 ++++- docs/intro/strategy.md | 101 ++++++++++++++++++++++++++++++++++--- docs/operators/tutorial.md | 79 ++--------------------------- mkdocs.yml | 5 ++ 4 files changed, 112 insertions(+), 85 deletions(-) diff --git a/docs/abra/quickstart.md b/docs/abra/quickstart.md index 9f0047c..af30eeb 100644 --- a/docs/abra/quickstart.md +++ b/docs/abra/quickstart.md @@ -4,8 +4,16 @@ title: Quick start There are a few ways to get started, here are some entrypoints listed below: -- If you're new around here and you'd like to learn how to deploy apps with `abra`, then a good place to start is the [new operators tutorial](/operators/tutorial). If you've already deployed some apps and would like to learn how to maintain them, then the [operators handbook](/operators/handbook) is the right place. +<div class="grid cards" markdown> -- If you're installing `abra` so you can do recipe packaging, take a look at the [new maintainers tutorial](/maintainers/tutorial). `abra` can help you check the quality of the recipe you've packaged and help you publish it to the public recipe catalogue. Then others can deploy your configuration :rocket: +- __Operators__ + + If you're new around here and you'd like to learn how to deploy apps with `abra`, then a good place to start is the [new operators tutorial](/operators/tutorial). If you've already deployed some apps and would like to learn how to maintain them, then the [operators handbook](/operators/handbook) is the right place. + +- __Maintainers__ + + If you're installing `abra` so you can do recipe packaging, take a look at the [new maintainers tutorial](/maintainers/tutorial). `abra` can help you check the quality of the recipe you've packaged and help you publish it to the public recipe catalogue. Then others can deploy your configuration :rocket: + +</div> If you run into any issues, please see the [troubleshooting page](/abra/trouble) :bomb: diff --git a/docs/intro/strategy.md b/docs/intro/strategy.md index cbf9675..d38c7b4 100644 --- a/docs/intro/strategy.md +++ b/docs/intro/strategy.md @@ -1,19 +1,106 @@ --- -title: Project strategy +title: Project Strategy --- -!!! note "Yes, we are blog" +From our experiences working and organising as Autonomic, the tech co-op who [initiated Co-op Cloud](https://autonomic.zone/blog/co-op-cloud/), we know that the progressive tech movement lack reliable and cost-effective technical means for providing a sustainable alternative to _Big Tech_Β© services which are marketed as "[cloud computing](https://en.wikipedia.org/wiki/Cloud_computing)". - 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. +## Technological Saviors? 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. -Technology alone will not save us. Simply deploying libre software is not enough. +> Technology alone will not save us +> +> Simply deploying libre software is not enough. -Our strategy is to mutualise our resources to facilitate 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. +Our strategy is to mutualise our resources to facilitate 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. From this base, we can focus on the urgent and necessary social organising work that goes beyond the technical question. + +## The Moving Parts + +_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/or extended as needed. We want to build a resilient and long-term sustainable project and that means allowing for different implementations, open formats and a diverse project organisation. Here are the main technical concepts listed below, + +``` mermaid +graph LR + A[Libre Software Apps] --> B{Recipe Packaging}; + B --> C[Command-line Tool]; + B --> D[Container Orchestrator]; + C --> D; +``` + +Once you [grok](https://en.wikipedia.org/wiki/Grok) this, you grok the moving parts of the entire project. You can then move on to [deploying your first app](/operators/tutorial/#deploy-your-first-app). + +### Libre Software Apps + +Libre software apps are tools- they take the shape of websites, mobile apps, and software clients that you may already use in your daily life, for example... + +<div class="grid cards" markdown> + +- :simple-nextcloud: __Nextcloud__ +- :simple-jitsi: __Jitsi__ +- :simple-wikimediacommons: __Mediawiki__ +- :fontawesome-solid-rocket: __Rocket.chat__ + +</div> + +...and many more. These apps are also often referred to as _open-Source_ or _Free-Software_. 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 to [proprietary systems]. + +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. + +There is a growing consensus in the free software community that containers are a useful and time saving format for distribution. + +!!! question "Why did you choose to use containers?" + + Learn more [in the FAQ section](/intro/faq/#why-containers). + +[free software licenses]: https://www.gnu.org/philosophy/free-sw.html +[nextcloud hub.docker.com account]: https://hub.docker.com/_/nextcloud +[proprietary systems]: https://en.wikipedia.org/wiki/Proprietary_software +[containers]: https://www.docker.com/resources/what-container + +### Recipe Packaging Format + +However, just having a container of an app is often not enough. The work required to deploy that app in a "production ready" setup 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. + +Individual free software projects can't take on all this responsibility. They provide the containers as is, in a secure and ready-to-go manner but it is up to service providers to worry about how the app is deployed. + +Therefore, Co-op Cloud proposes a packaging format, which we refer to as a recipe, that describes the entire production state of the app 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. Furthermore, as described below, we also don't rely on the actual Docker CLI itself either. We do however use a lot of the underlying libraries. + +!!! question "Why did you choose to use the compose specificiation?" + Learn more [in the FAQ section](/intro/faq/#why-use-the-compose-specification). + +[Each recipe] that Co-op cloud provides is described using the compose specification and makes use of the upstream project published container when possible (sometimes they don't publish one!). + +This is the core of our approach to working with the ecosystem of free software communities. We want to maximise the chances of sharing work, knowledge and build solidarity through concrete co-operation. + +[standards based compose specification]: https://compose-spec.io +[docker compose]: https://docs.docker.com/compose/ +[each recipe]: /recipes/ + +### Container Orchestrator + +Once we have our app packaged as a recipe, we need a deployment environment (e.g. a server & something to keep the containers running). Production deployments are typically expected to support a number of features which give hosters and end-users guarantees for stability. + +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 app rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design. + +!!! question "Why did you choose to use Docker Swarm?" + + Learn more [in the FAQ section](/intro/faq/#why-docker-swarm). + +[docker swarm]: https://docs.docker.com/engine/swarm/ + +### Command-line tool + +Finally, we need a tool to read the recipe package format and actually deploy the app. 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 apps and deploy them. `abra` is written in [Go](https://go.dev/) and uses a lot of the libraries that the `docker` and `docker-compose` CLIs use but does not rely on those interfaces directly. + +`abra` is our flagship command-line client but it does not need to be the only client. `abra` was designed in such a way that it complements a workflow which can still be done completely manually. If Co-op Cloud goes away tomorrow, our configuration commons would still be useful and usable. + +[abra]: /abra/ diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index 64bd86e..e72e3f6 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -2,82 +2,9 @@ title: New Operators Tutorial --- -## The moving parts - -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/or extended as needed. - -We want to build a resilient and long-term sustainable project and that means allowing for different implementations, open formats and a diverse project organisation. - -Here are the main technical concepts listed below, once you [grok](https://en.wikipedia.org/wiki/Grok) this, you grok the moving parts of the entire project. You can then move on to [deploying your first app](/operators/tutorial/#deploy-your-first-app). - -### Libre software apps - -Libre software apps are tools, websites & software clients 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 to [proprietary systems]. - -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. - -There is a growing consensus in the free software community that containers are a useful and time saving format for distribution. - -!!! question "Why did you choose to use containers?" - - Learn more [in the FAQ section](/intro/faq/#why-containers). - -[nextcloud]: https://nextcloud.com -[jitsi]: https://jitsi.org -[mediawiki]: https://mediawiki.org -[rocket.chat]: https://rocket.chat -[many more]: /recipes/ -[free software licenses]: https://www.gnu.org/philosophy/free-sw.html -[nextcloud hub.docker.com account]: https://hub.docker.com/_/nextcloud -[proprietary systems]: https://en.wikipedia.org/wiki/Proprietary_software -[containers]: https://www.docker.com/resources/what-container - -### The recipe packaging format - -However, just having a container of an app is often not enough. The work required to deploy that app in a "production ready" setup 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. - -Individual free software projects can't take on all this responsibility. They provide the containers as is, in a secure and ready-to-go manner but it is up to service providers to worry about how the app is deployed. - -Therefore, Co-op Cloud proposes a packaging format, which we refer to as a recipe, that describes the entire production state of the app 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. Furthermore, as described below, we also don't rely on the actual Docker CLI itself either. We do however use a lot of the underlying libraries. - -!!! question "Why did you choose to use the compose specificiation?" - Learn more [in the FAQ section](/intro/faq/#why-use-the-compose-specification). - -[Each recipe] that Co-op cloud provides is described using the compose specification and makes use of the upstream project published container when possible (sometimes they don't publish one!). - -This is the core of our approach to working with the ecosystem of free software communities. We want to maximise the chances of sharing work, knowledge and build solidarity through concrete co-operation. - -[standards based compose specification]: https://compose-spec.io -[docker compose]: https://docs.docker.com/compose/ -[each recipe]: /recipes/ - -### Container orchestrator - -Once we have our app packaged as a recipe, we need a deployment environment (e.g. a server & something to keep the containers running). Production deployments are typically expected to support a number of features which give hosters and end-users guarantees for stability. - -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 app rollbacks, automatic deploy failure handling, scaling, hybrid cloud setups and maintain a decentralised design. - -!!! question "Why did you choose to use Docker Swarm?" - - Learn more [in the FAQ section](/intro/faq/#why-docker-swarm). - -[docker swarm]: https://docs.docker.com/engine/swarm/ - -### Command-line tool - -Finally, we need a tool to read the recipe package format and actually deploy the app. 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 apps and deploy them. `abra` is written in [Go](https://go.dev/) and uses a lot of the libraries that the `docker` and `docker-compose` CLIs use but does not rely on those interfaces directly. - -`abra` is our flagship command-line client but it does not need to be the only client. `abra` was designed in such a way that it complements a workflow which can still be done completely manually. If Co-op Cloud goes away tomorrow, our configuration commons would still be useful and usable. - -[abra]: /abra/ +This tutorial assumes you understand the [frequently asked questions](/intro/faq/) as +well as [the moving parts](/intro/strategy/) of the technical problems Co-op +Cloud solves. If yes, proceed :smile: ## Deploy your first app diff --git a/mkdocs.yml b/mkdocs.yml index f35ba3e..2ac41fd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,6 +49,11 @@ markdown_extensions: - pymdownx.superfences - pymdownx.tabbed - pymdownx.tilde + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format nav: - "Introduction": From ee39912c88e2c9736ba69e08267c4aad071b05ce Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Sat, 10 Feb 2024 16:01:21 +0100 Subject: [PATCH 12/16] Small improvements to Operators tutorial - Made info boxes collapsible (default: closed) - Put links at end of sentences for clarity --- docs/operators/tutorial.md | 40 ++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index e72e3f6..c5b2eeb 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -2,9 +2,7 @@ title: New Operators Tutorial --- -This tutorial assumes you understand the [frequently asked questions](/intro/faq/) as -well as [the moving parts](/intro/strategy/) of the technical problems Co-op -Cloud solves. If yes, proceed :smile: +This tutorial assumes you understand the [frequently asked questions](/intro/faq/) as well as [the moving parts](/intro/strategy/) of the technical problems _Co-op Cloud_ solves. If yes, proceed :smile: ## Deploy your first app @@ -13,11 +11,14 @@ In order to deploy an app you need two things: 1. a server with SSH access and a public IP address 2. a domain name pointing to that server -The tutorial tries to help you make choices about which server and which DNS setup you need to run a Co-op Cloud deployment but it does not go into great depth about how to set up a new server. +This tutorial tries to help you make choices about which server and which DNS setup you need to run a _Co-op Cloud_ deployment but it does not go into great depth about how to set up a new server. -!!! question "Can `abra` help automate this?" +??? question "Can `abra` help automate this?" - `abra` can help bootstrap new servers & configure DNS records for you. We'll skip that for now since we're just getting started. See the [operators handbook](/operators/handbook) for more on these topics after you finish the tutorial. + Our `abra` tool can help bootstrap new servers & configure DNS records for + you. We'll skip that for now since we're just getting started. For more on + these topics after you finish the tutorial see the [operators + handbook](/operators/handbook). ### Server setup @@ -43,7 +44,7 @@ docker swarm init docker network create -d overlay proxy ``` -!!! question "Do you support multiple web proxies?" +??? question "Do you support multiple web proxies?" We do not know if it is feasible and convenient to set things up on an existing server with another web proxy which uses ports `:80` & `:443`. We'd happily receive reports and documentation on how to do this if you manage to set it up! @@ -58,7 +59,7 @@ Your entries in your DNS provider setup might look like the following. Where `116.203.211.204` can be replaced with the IP address of your server. -!!! question "How do I know my DNS is working?" +??? question "How do I know my DNS is working?" You can use a tool like `dig` on the command-line to check if your server has the necessary DNS records set up. Something like `dig +short <domain>` should show the IP address of your server if things are working. @@ -83,9 +84,9 @@ abra -h # check it works If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/coop-cloud/abra/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this. -!!! question "Can I install `abra` on my server?" +??? question "Can I install `abra` on my server?" - Yes, this is possible, see [this handbook entry](/operators/handbook/#running-abra-server-side) for more. The instructions for setup are a little different however. + Yes, this is possible. However, the instructions for this setup are different. For more info see [this handbook entry](/operators/handbook/#running-abra-server-side). #### Add your server @@ -100,21 +101,26 @@ It is important to note that `<domain>` here is a publicy accessible domain name You will now have a new `~/.abra/` folder on your local file system which stores all the configuration of your Co-op Cloud instance. -`abra` should now register this server as managed in your server listing: +By now `abra` should have registered this server as managed. To confirm this run: ``` abra server ls ``` -!!! warning "Beware of SSH dragons" +??? warning "Beware of SSH dragons :dragon_face:" - `abra` uses plain 'ol SSH under the hood and aims to make use of your existing SSH configurations in `~/.ssh/config` and interfaces with your running `ssh-agent` for password protected secret key files. + Under the hood `abra` uses plain 'ol `ssh` and aims to make use of your + existing SSH configurations in `~/.ssh/config` and interfaces with your + running `ssh-agent` for password protected secret key files. - Running `server add` with `-d/--debug` should help you debug what is going on under the hood. It's best to take a moment to read [this troubleshooting entry](/abra/trouble/#ssh-connection-issues) if you're running into SSH connection issues with `abra`. + Running `server add` with `-d` or `--debug` should help you debug what is going + on under the hood. If you're running into SSH connection issues with `abra` + take a moment to read [this troubleshooting + entry](/abra/trouble/#ssh-connection-issues). -!!! question "How do I share my configs in `~/.abra`?" +??? question "How do I share my configs in `~/.abra`?" - It's possible and quite easy, see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration) for more. + It's possible and quite easy, for more see [this handbook entry](/operators/handbook/#understanding-app-and-server-configuration). ### Web proxy setup @@ -154,7 +160,7 @@ abra app new nextcloud -S The `-S` or `--secrets` flag is used to generate secrets for the app: database connection password, root password and admin password. -!!! warning "Beware of password dragons" +??? warning "Beware of password dragons :dragon:" Take care, these secrets are only shown once on the terminal so make sure to take note of them! `abra` makes use of the [Docker secrets](/operators/handbook/#managing-secret-data) mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in `/run/secrets` on the container file system. From ac6cf7b5dc7e97d27946d5fe3f1e9900133bce12 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Mon, 12 Feb 2024 10:05:39 +0100 Subject: [PATCH 13/16] Improvements to Operators docs (manal verifying, CLI setup) - Move 'Validating abra binary checksums' to abra/install.md - Flatten #command-line-setup sub headings in Operators Handbook --- docs/abra/install.md | 18 ++++++++++++++++++ docs/operators/handbook.md | 12 ------------ docs/operators/tutorial.md | 25 ++++++++++++++++--------- 3 files changed, 34 insertions(+), 21 deletions(-) diff --git a/docs/abra/install.md b/docs/abra/install.md index 52741bd..cff525e 100644 --- a/docs/abra/install.md +++ b/docs/abra/install.md @@ -18,6 +18,24 @@ curl https://install.abra.coopcloud.tech | bash curl https://install.abra.coopcloud.tech | bash -s -- --rc ``` +## Manual verification + +You can download the `abra` binary yourself from the [releases +page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the +`checksums.txt` file and verify it's integrity with the following command. + +```bash +sha256sum -c checksums.txt --ignore-missing +``` + +If you see a line starting with `abra_...` which matches the filename you downloaded and it ends with `OK` - you're good to go! + +``` +abra_X.X.X-beta_linux_x86_64: OK +``` + +Otherwise, you downloaded a corrupted file and you should re-download it. + ## Compile from source Follow the guide [here](https://docs.coopcloud.tech/abra/hack/) diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md index 50e6c37..a0dedf1 100644 --- a/docs/operators/handbook.md +++ b/docs/operators/handbook.md @@ -205,18 +205,6 @@ At time of writing (Jan 2022), we think there is a limitation in our design whic This may be possible to overcome if someone really needs it, we encourage people to investigate. We've found that often there are limitations in the actual software which don't support this anyway and several of the current operators simply use a new domain per app. -## Validating `abra` binary checksums - - You can download `abra` yourself from the [releases page](https://git.coopcloud.tech/coop-cloud/abra/releases) along with the `checksums.txt` file. - -```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. - ## Creating a new server `abra server new` can create servers if you have an account with a supported 3rd party integration. We currently support [Servers.coop](https://servers.coop) & [Hetzner](https://hetzner.com). The process of creating a new server usually goes like this: diff --git a/docs/operators/tutorial.md b/docs/operators/tutorial.md index c5b2eeb..09e7c81 100644 --- a/docs/operators/tutorial.md +++ b/docs/operators/tutorial.md @@ -63,23 +63,30 @@ Where `116.203.211.204` can be replaced with the IP address of your server. You can use a tool like `dig` on the command-line to check if your server has the necessary DNS records set up. Something like `dig +short <domain>` should show the IP address of your server if things are working. -### Command-line setup +### Install `abra` -#### Install `abra` - -Now we can install [`abra`](/abra) locally on your machine and hook it up to your server. - -We support a script-based installation method (script source [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer)): +Now we can install [`abra`](/abra) locally on your machine and hook it up to +your server. We support a script-based installation method ([script source](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer)): ```bash curl https://install.abra.coopcloud.tech | bash ``` -The installer will verify the downloaded binary checksum. You may need to add the `~/.local/bin/` directory with your `$PATH` in order to run the executable. You can validate that everything is in working order by listing the default help output: +The installer will verify the downloaded binary checksum. If you prefer, you can +[manually verify](/abra/install/#manual-verification) the binary, and then +manally place it in one the directories in your `$PATH` variable. To validate +that everything is working try listing the `--help` command or `-h` to view +output: + +```bash +abra -h +``` + +You may need to add the `~/.local/bin/` directory to your `$PATH` variable, in +order to run the executable. ```bash export PATH=$PATH:$HOME/.local/bin -abra -h # check it works ``` If you run into issues during installation, [please report a ticket](https://git.coopcloud.tech/coop-cloud/abra/issues/new) :pray: Once you're all set up, we **highly** recommend configuring command-line auto-completion for `abra`. See `abra autocomplete -h` for more on how to do this. @@ -88,7 +95,7 @@ If you run into issues during installation, [please report a ticket](https://git Yes, this is possible. However, the instructions for this setup are different. For more info see [this handbook entry](/operators/handbook/#running-abra-server-side). -#### Add your server +### Add your server Now you can connect `abra` with your server. You should have a working SSH configuration before you can do this (e.g. a matching `Host <server-domain>` entry in `~/.ssh/config` with the correct SSH connection details). That means you can run `ssh <server-domain>` on your command-line and everything Works :tm:. From b9c7ebd500702542da0761be5ba5187afac39f4a Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Mon, 12 Feb 2024 10:50:13 +0100 Subject: [PATCH 14/16] update Moving Parts flow chart --- docs/intro/strategy.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/intro/strategy.md b/docs/intro/strategy.md index d38c7b4..4172d37 100644 --- a/docs/intro/strategy.md +++ b/docs/intro/strategy.md @@ -24,10 +24,9 @@ _Co-op Cloud_ is made up of a few simple, composable pieces. The system does not ``` mermaid graph LR - A[Libre Software Apps] --> B{Recipe Packaging}; - B --> C[Command-line Tool]; - B --> D[Container Orchestrator]; - C --> D; + A[Libre Software\n Apps] --> B{Recipe Packaging}; + B --> C[CLI Tool]; + C --> D[Container\n Orchestrator]; ``` Once you [grok](https://en.wikipedia.org/wiki/Grok) this, you grok the moving parts of the entire project. You can then move on to [deploying your first app](/operators/tutorial/#deploy-your-first-app). From a1d9cf8940d42af693c5289999ab34d7da5e3494 Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 21 Feb 2024 20:50:27 +0100 Subject: [PATCH 15/16] fix missing --- in Resolution 017 --- docs/federation/resolutions/in-progress/017.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/federation/resolutions/in-progress/017.md b/docs/federation/resolutions/in-progress/017.md index d8c0ef4..e1a3003 100644 --- a/docs/federation/resolutions/in-progress/017.md +++ b/docs/federation/resolutions/in-progress/017.md @@ -1,5 +1,6 @@ --- title: "Resolution 017" +--- - Topic: BeWater joins the Co-op Cloud Federation - Date: 30-01-2024 From 623a0be0b0c31d8bd00e9dd100908d9586244dbc Mon Sep 17 00:00:00 2001 From: basebuilder <bases@eotl.supply> Date: Wed, 21 Feb 2024 20:51:32 +0100 Subject: [PATCH 16/16] fix Resolution state in sidebar --- mkdocs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 2ac41fd..fa356f9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -122,10 +122,9 @@ nav: - federation/resolutions/passed/014.md - federation/resolutions/passed/015.md - "In Progress": + - federation/resolutions/in-progress/013.md - federation/resolutions/in-progress/016.md - federation/resolutions/in-progress/017.md - - "Draft": - - federation/resolutions/drafts/013.md - "Minutes": - federation/minutes/index.md - "2022":