diff --git a/Dockerfile b/Dockerfile index 8b1710b..45ab3ea 100644 --- a/Dockerfile +++ b/Dockerfile @@ -8,7 +8,4 @@ WORKDIR /docs RUN apk add --no-cache curl -RUN pip install \ - mkdocs-material~=9.5.7 \ - mkdocs-material-extensions~=1.3.1 \ - mkdocs-awesome-pages-plugin==2.9.2 +RUN pip install -r requirements.txt diff --git a/docs/federation/resolutions/in-progress/017.md b/docs/federation/resolutions/in-progress/017.md index 77cf406..d8c0ef4 100644 --- a/docs/federation/resolutions/in-progress/017.md +++ b/docs/federation/resolutions/in-progress/017.md @@ -1,10 +1,9 @@ --- title: "Resolution 017" ---- - Topic: BeWater joins the Co-op Cloud Federation - Date: 30-01-2024 -- Deadline: 13-02-2024 +- Deadline: 21-02-2024 - Size: Large ### Summary diff --git a/docs/get-involved/support.md b/docs/get-involved/support.md new file mode 100644 index 0000000..69d3dbb --- /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). + +
+ +- __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 } + +- __Join The 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 } + +
diff --git a/docs/intro/comparisons.md b/docs/intro/comparisons.md new file mode 100644 index 0000000..4d48564 --- /dev/null +++ b/docs/intro/comparisons.md @@ -0,0 +1,158 @@ +--- +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. + + +### 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. + + +### 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. 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/docs/maintainers/handbook.md b/docs/maintainers/handbook.md index a2cfc50..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//.env` and when you run `abra app config ` 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//.env` and when you run `abra app config ` you're editing this file. ### `abra.sh` @@ -433,7 +433,7 @@ You can pass `--publish` to have `abra` automatically publish those changes. [`coop-cloud/rallly` repository](https://git.coopcloud.tech/coop-cloud/rallly) (probably [using `abra recipe release`](#how-do-i-release-a-new-recipe-version)), it automatically does the -[recipe catalogue generation steps(#how-do-i-generate-the-recipe-catalogue)" +[recipe catalogue generation steps](#how-do-i-generate-the-recipe-catalogue)" 1. Check whether tag builds are already trying to run: go to https://build.coopcloud.tech, search for the recipe name (in this case taking 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` diff --git a/mkdocs.yml b/mkdocs.yml index 8da7ba6..f35ba3e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -55,6 +55,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 @@ -92,6 +93,7 @@ nav: - "Cheat Sheet": abra/cheat-sheet.md - "Get Involved": - get-involved/index.md + - "Support Us": get-involved/support.md - "Federation": - federation/index.md - "Bylaws": federation/bylaws.md