diff --git a/docs/apps.md b/docs/apps.md index 49a6ef3..b7b5d08 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -2,29 +2,29 @@ title: Application catalogue --- -# Applications +## Applications | **Name** | **Status** | **Image** | **Healtcheck** | **Backups** | **Email** | **CI** | **Single-Sign-On** | -| ------------------ | ---------- | --------- | ---------- | ----------- | --------- | ------ | ------------------ | -| [Adapt Authoring] | ❸🍎 | βΉπŸ’£ | βœ… | ❌ | ❌ | β·πŸ’› | ❌ | -| [CodiMD] | β·πŸ’› | βΆπŸ’š | βœ… | ❌ | ❌ | β·πŸ’› | βΆπŸ’š (OAuth) | -| [InvoiceNinja] | βΉπŸ’£ | ? | ? | ? | ? | ❌ | ? | -| [H5ai] | ❸🍎 | ❸🍎 | βœ… | ❌ | n/a | ❌ | ❌ | -| [Keycloak] | β·πŸ’› | βΆπŸ’š | βœ… | ? | ❸🍎 | β·πŸ’› | n/a | -| [Keyoxide] | β·πŸ’› | βΆπŸ’š | βœ… | ? | n/a | ❌ | n/a | -| [Kimai] | ? | β·πŸ’› | ? | ? | ? | β·πŸ’› | πŸ’£ | -| [Kutt] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | ❌ | ❌ | -| [Matomo] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | β·πŸ’› | ❌ | -| [Mailu] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | n/a | β·πŸ’› | ❌ | -| [Matrix (Synapse)] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | ❌ | ❌ | -| [Mediawiki] | β·πŸ’› | βΆπŸ’š | ❌ | ❌ | βΆπŸ’š | β·πŸ’› | β·πŸ’› (SAML, OAuth) | -| [Nextcloud] | β·πŸ’› | βΆπŸ’š | βœ… | ❌ | βΆπŸ’š | β·πŸ’› | ❸🍎 (OAuth) | -| [PHPServerMon] | β·πŸ’› | βΆπŸ’š | ❌ | ❌ | βΆπŸ’š | β·πŸ’› | -| [Rocket.Chat] | β·πŸ’› | βΆπŸ’š | βœ… | ❌ | βΆπŸ’š | β·πŸ’› | βΆπŸ’š (OAuth) | -| [SelfOSS] | ❸🍎 | ❸🍎 | βœ… | ❌ | ❌ | ❸🍎 | πŸ’£ | -| [Statping] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❸🍎 | ❌ | ❌ | -| [Wallabag] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | β·πŸ’› | ❌ | -| [Wordpress] | βΆπŸ’š | βΆπŸ’š | βœ… | βœ… | βΆπŸ’š | β·πŸ’› | ❌ | +| ------------------ | ---------- | --------- | -------------- | ----------- | --------- | ------ | ------------------ | +| [Adapt Authoring] | ❸🍎 | βΉπŸ’£ | βœ… | ❌ | ❌ | β·πŸ’› | ❌ | +| [CodiMD] | β·πŸ’› | βΆπŸ’š | βœ… | ❌ | ❌ | β·πŸ’› | βΆπŸ’š (OAuth) | +| [InvoiceNinja] | βΉπŸ’£ | ? | ? | ? | ? | ❌ | ? | +| [H5ai] | ❸🍎 | ❸🍎 | βœ… | ❌ | n/a | ❌ | ❌ | +| [Keycloak] | β·πŸ’› | βΆπŸ’š | βœ… | ? | ❸🍎 | β·πŸ’› | n/a | +| [Keyoxide] | β·πŸ’› | βΆπŸ’š | βœ… | ? | n/a | ❌ | n/a | +| [Kimai] | ? | β·πŸ’› | ? | ? | ? | β·πŸ’› | πŸ’£ | +| [Kutt] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | ❌ | ❌ | +| [Matomo] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | β·πŸ’› | ❌ | +| [Mailu] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | n/a | β·πŸ’› | ❌ | +| [Matrix (Synapse)] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | ❌ | ❌ | +| [Mediawiki] | β·πŸ’› | βΆπŸ’š | ❌ | ❌ | βΆπŸ’š | β·πŸ’› | β·πŸ’› (SAML, OAuth) | +| [Nextcloud] | β·πŸ’› | βΆπŸ’š | βœ… | ❌ | βΆπŸ’š | β·πŸ’› | ❸🍎 (OAuth) | +| [PHPServerMon] | β·πŸ’› | βΆπŸ’š | ❌ | ❌ | βΆπŸ’š | β·πŸ’› | +| [Rocket.Chat] | β·πŸ’› | βΆπŸ’š | βœ… | ❌ | βΆπŸ’š | β·πŸ’› | βΆπŸ’š (OAuth) | +| [SelfOSS] | ❸🍎 | ❸🍎 | βœ… | ❌ | ❌ | ❸🍎 | πŸ’£ | +| [Statping] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❸🍎 | ❌ | ❌ | +| [Wallabag] | ❸🍎 | βΆπŸ’š | ❌ | ❌ | ❌ | β·πŸ’› | ❌ | +| [Wordpress] | βΆπŸ’š | βΆπŸ’š | βœ… | βœ… | βΆπŸ’š | β·πŸ’› | ❌ | [adapt authoring]: https://git.autonomic.zone/coop-cloud/adapt_authoring [codimd]: https://git.autonomic.zone/coop-cloud/codimd @@ -46,7 +46,7 @@ title: Application catalogue [wallabag]: https://git.autonomic.zone/coop-cloud/wallabag [wordpress]: https://git.autonomic.zone/coop-cloud/wordpress -# Developer tools +## Developer tools | **Name** | **Status** | **Image** | **Hltchk** | **Backups** | **Email** | **CI** | **Single-Sign-On** | | --------------------- | ---------- | --------- | ---------- | ----------- | --------- | ------ | ------------------ | @@ -64,7 +64,7 @@ title: Application catalogue [strapi]: https://git.autonomic.zone/coop-cloud/strapi [renovate bot]: https://git.autonomic.zone/coop-cloud/renovate -# Utilities +## Utilities | πŸ”§ **Name** | **Status** | **Image** | **Hltchk** | **Backups** | **Email** | **CI** | **Single-Sign-On** | | ---------------------- | ---------- | --------- | ---------- | ----------- | --------- | ------ | ------------------ | @@ -82,7 +82,7 @@ title: Application catalogue [traefik]: https://git.autonomic.zone/coop-cloud/traefik [traefik forward auth]: https://git.autonomic.zone/coop-cloud/traefik-forward-auth -# Graveyard +## Graveyard | ☠ **Name** | **Status** | **Image** | **Hltchk** | **Backups** | **Email** | **CI** | **Single-Sign-On** | | ---------- | ---------- | --------- | ---------- | ----------- | --------- | ------ | ------------------ | @@ -90,9 +90,9 @@ title: Application catalogue [statuspal]: https://git.autonomic.zone/coop-cloud/statuspal -# Status legend: +## Status legend -## Overall: +### Overall - 🌈🌈: everything in βΆπŸ’š + Single-Sign-On - βΆπŸ’š: upstream image, backups, email, healthcheck, integration testing @@ -100,28 +100,28 @@ title: Application catalogue - ❸🍎: missing 3-4 items from βΆπŸ’š or no upstream image - βΉπŸ’£: alpha -## Image +### Image - βΆπŸ’š: official upstream image - β·πŸ’›: semi-official / actively-maintained image - ❸🍎: 3rd-party image - βΉπŸ’£: our own custom image -## Email +### Email - βΆπŸ’š: automatic (using environment variables) - β·πŸ’›: mostly automatic - ❸🍎: manual - ❌: none -## CI +### CI - βΆπŸ’š: as β·πŸ’›, plus healthcheck - β·πŸ’›: auto secrets + networks - ❸🍎: basic deployment using `stack-ssh-deploy`, manual secrets + networks - ❌: none -## Single-Sign-On +### Single-Sign-On - βΆπŸ’š: automatic (using environment variables) - β·πŸ’›: mostly automatic diff --git a/docs/faq.md b/docs/faq.md index ad4e3ca..823d656 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -4,17 +4,37 @@ title: Frequently asked questions ## What is the Co-op Cloud? +<<<<<<< HEAD Co-op Cloud aims to make hosting free software applications simple for small providers. It uses the latest container technologies and innovations and configurations are shared into [the commons](https://en.wikipedia.org/wiki/Commons) for the benefit of all. The project is intended for small service providers such as tech co-operatives who are looking to standardise around an open, transparent and scalable infrastructure. +======= +The Co-op Cloud is a project which aims to make self-hosting free software applications simple! It's a project which fits in alongside others like [Cloudron](https://www.cloudron.io/), [Yunohost](https://yunohost.org/) and [Freedombone](https://freedombone.net/) and others but has its own specific focus. The project is intended for existing small service providers and cooperatives already involved in hosting work who are looking for alternatives. + +## Which technologies? + +The core technologies are free software and enjoy wide adoption across free +software developer communities. + +- [Containers](#why-containers) +- [Docker compose](#why-docker-compose) +- [Docker swarm](#why-docker-swarm) + +## Who packages your applications? +>>>>>>> a87bafda8ce37f7139aaf3f598ae91d77a28332e ## Who is behind the project? The project was started by workers at [Autonomic](https://autonomic.zone/) which is a [workers co-operative](https://en.wikipedia.org/wiki/Worker_cooperative) providing technologies and infrastructure to empower users to make a positive impact on the world. +<<<<<<< HEAD We use Co-op Cloud in production amongst other systems. +======= +## Why containers? +>>>>>>> a87bafda8ce37f7139aaf3f598ae91d77a28332e ## Why Co-op Cloud? +<<<<<<< HEAD #### πŸ‘ - πŸ‘ Thin "ease of use" layer on top of already standardised tooling - πŸ‘ Extremely modular @@ -35,6 +55,19 @@ We use Co-op Cloud in production amongst other systems. 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, the Cooperative Cloud isn't meant to be a replacement for these others projects. Here is a short overview of the pros/cons we see and how that relates to our goals here. +======= +## Why Docker Compose? + +## Why Docker Swarm? + +## Why start another project? + +One of our core principles is to not re-invent the wheel. However, fitting needs into existing projects doesn't always work out. Some of the developers on this project were also once developers on the other existing projects. + +## What about `$alternative`? + +We have our critiques of other similar projects which are already up-and-running in the ecosystem. However, the Co-op Cloud isn't meant to be a replacement for these projects. Here is a short overview of the pros/cons we see and how that relates to our goals here. +>>>>>>> a87bafda8ce37f7139aaf3f598ae91d77a28332e ### Cloudron @@ -149,6 +182,10 @@ TODO. TODO. -# What licensing model does the project use? +## What licensing model do you use? +<<<<<<< HEAD The Cooperative Cloud is and will always be available under [copyleft licenses](https://en.wikipedia.org/wiki/Copyleft). +======= +The Co-op Cloud will always be available under copyleft licenses. +>>>>>>> a87bafda8ce37f7139aaf3f598ae91d77a28332e diff --git a/docs/index.md b/docs/index.md index 0f67b50..5c8b3a3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,18 +7,21 @@ title: Co-op Cloud Welcome to the Co-op Cloud technical documentation. This documentation is primarily meant for cooperatives and other small service providers already doing free software hosting who are interested in the project and thinking about doing some early-adopter testing. ## Getting started + If you're new to the project, then head over to the [getting started - guide](/overview/). +guide](/overview/). ## Apps + If you want to see what applications are already available, then check out the [app catalogue](/apps/). ## FAQ + If you're trying to understand more about the project please see [the FAQ](/faq/). ## Important Note This project is still alpha quality software. Please take that into consideration before using 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 and ideas. diff --git a/docs/overview.md b/docs/overview.md index 9ac58b7..a00bd65 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -2,4 +2,63 @@ title: Technical overview --- -TODO. +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. + +- [Free software applications](#free-software-applications) +- [The packaging format](#the-packaging-format) +- [Container orchestrator](#container-orchestrator) +- [Command-line tool](#command-line-tool) + +## Free software applications + +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 [standards based compose specification] which is most commonly used by the [Docker compose] tool. + +[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 Docker compose [in the FAQ section](faq/#why-docker-compose). + +[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-operative 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 + +## Moving forward + +Now that you've got an overview, it is time to [deploy your first application]. + +[deploy your first application]: /deploy/