From b5afd99f66fae80691a1d034f35d682942e3864f Mon Sep 17 00:00:00 2001 From: basebuilder Date: Mon, 5 Feb 2024 15:27:57 +0100 Subject: [PATCH 1/4] Reduce UI clutter & improve Recipes - Remove word ___ Guide from various pages - Camel Case titles - Move Recipes sub-page of Abra --- docs/abra/recipes.md | 108 ++++++++++++++++++++++++++++++++++++++ docs/maintainers/index.md | 6 +-- docs/operators/index.md | 2 +- docs/organisers/index.md | 4 +- docs/recipes/index.md | 83 ----------------------------- docs/styles/extra.css | 34 ++++++++++++ mkdocs.yml | 38 ++++++++------ 7 files changed, 169 insertions(+), 106 deletions(-) create mode 100644 docs/abra/recipes.md delete mode 100644 docs/recipes/index.md diff --git a/docs/abra/recipes.md b/docs/abra/recipes.md new file mode 100644 index 0000000..f8fd9b1 --- /dev/null +++ b/docs/abra/recipes.md @@ -0,0 +1,108 @@ +--- +title: Recipes +--- + +_Recipes_ are what we call the configuration file used to deploy apps with our `abra` tool. A longer explanation is in the [glossary](/glossary#recipe). Our _Catalogue_ is a web interface for explore the currently available configurations, therefore which apps can be deployed. + +### Catalogue + +Our catalogue is located at [recipes.coopcloud.tech](https://recipes.coopcloud.tech/) and regularly updated :cooking: + +[Browse Our Recipes](https://recipes.coopcloud.tech/){ .md-button .md-button--primary } + +The catalogue is a helpful place to understand the status of app recipes, who is taking care of the recipes, and who is maintaining deployed instances of which apps. To understand the various scores on recipes, read further. + +## Status, Features, Score + +Each recipe `README.md` has a "metadata" section, to help communicate the overall status of the recipe, and which features are supported. Here's an example, from [the Wordpress recipe](https://git.coopcloud.tech/coop-cloud/wordpress/): + +``` + + +* **Category**: Apps +* **Status**: 3, stable +* **Image**: [`wordpress`](https://hub.docker.com/_/wordpress), 4, upstream +* **Healthcheck**: Yes +* **Backups**: Yes +* **Email**: 3 +* **Tests**: 2 +* **SSO**: No + + +``` + +Currently, recipe maintainers need to update the scores in this section manually. The specific meanings of the scores are: + +### Status (overall score) + +| Score | Description | +| ----- | ------------------------------------ | +| [5](#){ .md-score .md-score-5 } | Everything in 4 + Single-Sign-On | +| [4](#){ .md-score .md-score-4 } | Upstream image, backups, email, healthcheck, integration testing | +| [3](#){ .md-score .md-score-3 } | Upstream image, missing 1-2 items from 4 | +| [2](#){ .md-score .md-score-2 } | Missing 3-4 items from 4 or no upstream image | +| [1](#){ .md-score .md-score-1 } | Alpha | + +### Image + +| Score | Description | +| ----- | ------------------------------------ | +| 4 | Official upstream image | +| 3 | Semi-official / actively-maintained image | +| 2 | 3rd-party image | +| 1 | Our own custom image | + +### Email + +| Score | Description | +| ----- | ------------------------------------ | +| 3 | Automatic (using environment variables) | +| 2 | Mostly automatic | +| 1 | Manual | +| 0 | None | +| N/A | App doesn't send email | + +### CI (Continuous Integration) + +| Score | Description | +| ----- | ------------------------------------ | +| 3 | As 2, plus healthcheck | +| 2 | Auto secrets + networks | +| 1 | Basic deployment using `stack-ssh-deploy`, manual secrets + networks | +| 0 | None | + +### Single-Sign-On + +| Score | Description | +| ----- | ------------------------------------ | +| 3 | Automatic (using environment variables) | +| 2 | Mostly automatic | +| 1 | Manual | +| 0 | None | +| N/A | App doesn't support SSO | + +## Requesting Recipes + +If you'd like to see a new recipe packaged there are two options for you. First is to contribte one as a _Maintainer_ +The second option is to make a request on the `recipes-wishlist` repository issue tracker. + +If no one is around to help, you can always take a run at it yourself, go to the [Maintainers](/maintainers/) section to help you on your way. + +
+ +- __Contribute Recipes__ + + Do you not see the recipe for the app you use or make? We especially love recipe maintainers :heart: + + [Create a Recipe](/maintainers/){ .md-button .md-button--primary } + +- __Request A Recipe__ + + Don't feel up to the task? Open an issue in the `recipes-wishlist` repository + + [Request Recipe](https://git.coopcloud.tech/coop-cloud/recipes-wishlist){ .md-button .md-button--primary } + +
+ +We've seen nice things happen when the requesters are also willing to take an active role in testing the new recipe. Teaming up with whoever volunteers to help do the packaging is best. + diff --git a/docs/maintainers/index.md b/docs/maintainers/index.md index 1b2cc13..484d069 100644 --- a/docs/maintainers/index.md +++ b/docs/maintainers/index.md @@ -1,18 +1,18 @@ --- -title: Maintainers Guide +title: Maintainers --- Welcome to the maintainers guide! Maintainers are typically individuals who have a stake in building up and maintaining our digital configuration commons, the recipe configurations. Maintainers help keep recipes configurations up to date, respond to issues in a timely manner, help new users within the community and recruit new maintainers when possible.
-- __New maintainers tutorial__ +- __New Maintainers Tutorial__ If you want to package a recipe and/or become a maintainer, start here :rocket: [Get Started](/maintainers/tutorial){ .md-button .md-button--primary } -- __Packaging handbook__ +- __Packaging Handbook__ One-stop shop for all you need to know to package recipes :package: diff --git a/docs/operators/index.md b/docs/operators/index.md index 5a9c2fd..f3d0cfb 100644 --- a/docs/operators/index.md +++ b/docs/operators/index.md @@ -1,5 +1,5 @@ --- -title: Operators Guide +title: Operators --- Welcome to the operators guide! Operators are typically individuals, members of tech co-ops or collectives who provide services powered by Co-op Cloud. This documentation is meant to help new & experienced operators manage their deployments as well as provide a space for sharing tricks & tips for keeping things running smoothly. diff --git a/docs/organisers/index.md b/docs/organisers/index.md index 1f34fe1..16fdb06 100644 --- a/docs/organisers/index.md +++ b/docs/organisers/index.md @@ -1,12 +1,12 @@ --- -title: Organisers Guide +title: Organisers --- Welcome to the organisers guide! Organisers are folks who focus on the social work in the project. Speaking for the project at talks, helping new tech co-ops & collectives join, keeping an eye out for funding opportunities, seeing what things come up in the community chats, etc. It's important work.
-- __Organisers handbook__ +- __Organisers Handbook__ One-stop shop for all you need to know to organise in the community :sparkles: diff --git a/docs/recipes/index.md b/docs/recipes/index.md deleted file mode 100644 index fa2fc28..0000000 --- a/docs/recipes/index.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Recipes ---- - -!!! note "Unsure of what a "recipe" is exactly?" - - Not to worry, we've got you covered, check out our [glossary page entry](/glossary#recipe). - -## Catalogue - -The recipe catalogue is a web interface for exploring -what kind of configurations we have available in the project and therefore what apps can be deployed. - -It aims to be a helpful place to understand the status of apps, who is taking care of the configs and who is maintaining deployed instances of which app. - -The recipe catalogue is available on [recipes.coopcloud.tech](https://recipes.coopcloud.tech/). - -## Status / features / scoring - -Each recipe README has a "metadata" section, to help communicate the overall status of the recipe, and which features are supported. Here's an example, from [the Wordpress recipe](https://git.coopcloud.tech/coop-cloud/wordpress/): - -``` - - -* **Category**: Apps -* **Status**: 3, stable -* **Image**: [`wordpress`](https://hub.docker.com/_/wordpress), 4, upstream -* **Healthcheck**: Yes -* **Backups**: Yes -* **Email**: 3 -* **Tests**: 2 -* **SSO**: No - - -``` - -Currently, recipe maintainers need to update the scores in this section manually. The specific meanings of the scores are: - -### Status (overall score) - -- 5: everything in 4 + Single-Sign-On -- 4: upstream image, backups, email, healthcheck, integration testing -- 3: upstream image, missing 1-2 items from 4 -- 2: missing 3-4 items from 4 or no upstream image -- 1: alpha - -### Image - -- 4: official upstream image -- 3: semi-official / actively-maintained image -- 2: 3rd-party image -- 1: our own custom image - -### Email - -- 3: automatic (using environment variables) -- 2: mostly automatic -- 1: manual -- 0: none -- N/A: app doesn't send email - -### CI - -- 3: as 2, plus healthcheck -- 2: auto secrets + networks -- 1: basic deployment using `stack-ssh-deploy`, manual secrets + networks -- 0: none - -### Single-Sign-On - -- 3: automatic (using environment variables) -- 2: mostly automatic -- 1: manual -- 0: none -- N/A: app doesn't support SSO - -## Wishlist - -If you'd like to see a new recipe packaged, make a request on the [recipes-wishlist](https://git.coopcloud.tech/coop-cloud/recipes-wishlist) repository issue tracker. - -We've seen nice things happen when the requesters are also willing to take an active role in testing the new recipe. Teaming up with whoever volunteers to help do the packaging is best. - -If no one is around to help, you can always take a run at it yourself, we have [a section](/maintainers/) ready to help you on your way. diff --git a/docs/styles/extra.css b/docs/styles/extra.css index 57b0e73..9375b0d 100644 --- a/docs/styles/extra.css +++ b/docs/styles/extra.css @@ -46,3 +46,37 @@ background-color: #6A9CFF !important; color: var(--md-primary-bg-color) !important; } + +.md-score { + display: inline-block; + padding: .15em .75em; + cursor: normal; + border-radius: .25em; + font-size: .85em; + font-weight: 700; +} + +.md-score-5 { + color: #ffffff !important; + background-color: #28a745; +} + +.md-score-4 { + color: #ffffff !important; + background-color: #007bff; +} + +.md-score-3 { + color: #ffffff !important; + background-color: #ffc107; +} + +.md-score-2 { + color: #ffffff !important; + background-color: #dc3545; +} + +.md-score-1 { + color: #ffffff !important; + background-color: #343a40; +} diff --git a/mkdocs.yml b/mkdocs.yml index 1d2d58a..3172112 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ --- site_author: Co-op Cloud -site_name: "Co-op Cloud: Public Interest Infrastructure" +site_name: "Co-op Cloud: Docs" site_url: https://docs.coopcloud.tech use_directory_urls: true @@ -48,27 +48,32 @@ 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": - index.md - - "Frequently asked questions": intro/faq.md - - "Project strategy": intro/strategy.md - - "Project status": intro/bikemap.md - - "Managed hosting": intro/managed.md - - "Get in touch": intro/contact.md + - "Frequently Asked Questions": intro/faq.md + - "Project Strategy": intro/strategy.md + - "Project Status": intro/bikemap.md + - "Managed Hosting": intro/managed.md + - "Get In Touch": intro/contact.md - "Credits": intro/credits.md - - "Operators Guide": + - "Operators": - operators/index.md - - "New operators tutorial": operators/tutorial.md - - "Operations handbook": operators/handbook.md - - "Maintainers Guide": + - "New Operators Tutorial": operators/tutorial.md + - "Operations Handbook": operators/handbook.md + - "Maintainers": - maintainers/index.md - - "New maintainers tutorial": maintainers/tutorial.md - - "Packaging handbook": maintainers/handbook.md - - "Organisers Guide": + - "New Maintainers Tutorial": maintainers/tutorial.md + - "Packaging Handbook": maintainers/handbook.md + - "Organisers": - organisers/index.md - - "Organising handbook": organisers/handbook.md + - "Organisers Handbook": organisers/handbook.md - "Funding applications": - organisers/funding-applications/index.md - organisers/funding-applications/culture-of-solidarity.md @@ -79,13 +84,12 @@ nav: - "Proposals": - organisers/proposals/index.md - organisers/proposals/federation.md - - "Recipes": - - recipes/index.md - "Abra": - abra/index.md - "Install": abra/install.md - - "Quick start": abra/quickstart.md + - "Quick Start": abra/quickstart.md - "Upgrade": abra/upgrade.md + - "Recipes": abra/recipes.md - "Hack": abra/hack.md - "Troubleshoot": abra/trouble.md - "Cheat Sheet": abra/cheat-sheet.md From 0187af4e8d096da42fa18a9724fffe2792f049e5 Mon Sep 17 00:00:00 2001 From: basebuilder Date: Mon, 5 Feb 2024 15:58:00 +0100 Subject: [PATCH 2/4] Improve Get In Touch cpage --- docs/intro/contact.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/intro/contact.md b/docs/intro/contact.md index c53cb71..6ff57ba 100644 --- a/docs/intro/contact.md +++ b/docs/intro/contact.md @@ -2,16 +2,33 @@ title: Get in touch --- -## Email +We welcome developers, sys-admins, designers, UX folks, Q&A testers, and passionate users to join us. +Pick the right medium for your interests. -[`helo@coopcloud.tech`](mailto:helo@coopcloud.tech) +
-## Chat +- __Chat__ -### Matrix + [Matrix](https://matrix.org) is our chat platform of choice, we are happy to hear from you there :speech_left: -Here is a link to the [Matrix space](https://matrix.to/#/!xSMwGbdVehScXcIFwS:autonomic.zone?via=autonomic.zone&via=matrix.org&via=1312.media) to see all channels. + [Join Chats](https://matrix.to/#/!xSMwGbdVehScXcIFwS:autonomic.zone?via=autonomic.zone&via=matrix.org&via=1312.media){ .md-button .md-button--primary } -## Forum +- __Codebases__ -[`community.coops.tech`](https://community.coops.tech/) + Get straight to looking at our code or filing issues, hop to our Gitea instance :sunglasses: + + [Browse Code](https://git.coopcloud.tech/coop-cloud){ .md-button .md-button--primary } + +- __Forum__ + + If you prefer communicating asynchronously with topical categories :tropical_drink: + + [Our Forum](https://community.coops.tech/){ .md-button .md-button--primary } + +- __Email__ + + If you like it old school, feel free to fire up port 25 and send us a `HELO` message :email: + + [Email Us](mailto:helo@coopcloud.tech){ .md-button .md-button--primary } + +
From ab5ac034e9d8f563816cb8e5df76167b4d6a34c0 Mon Sep 17 00:00:00 2001 From: decentral1se Date: Mon, 5 Feb 2024 13:39:03 +0100 Subject: [PATCH 3/4] fix: bump also Dockerfile deps --- Dockerfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 7b1c379..8b1710b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,5 +10,5 @@ RUN apk add --no-cache curl RUN pip install \ mkdocs-material~=9.5.7 \ - mkdocs-material-extensions~=1.1.1 \ - mkdocs-awesome-pages-plugin~=2.9.1 + mkdocs-material-extensions~=1.3.1 \ + mkdocs-awesome-pages-plugin==2.9.2 From 568c27dc9ab352dea864f92e6ed72d6137b03996 Mon Sep 17 00:00:00 2001 From: basebuilder Date: Mon, 12 Feb 2024 11:01:21 +0100 Subject: [PATCH 4/4] spelling, word choice, and link fixes to new Abra -> Recipes page --- docs/abra/recipes.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/abra/recipes.md b/docs/abra/recipes.md index f8fd9b1..1de87ca 100644 --- a/docs/abra/recipes.md +++ b/docs/abra/recipes.md @@ -2,7 +2,7 @@ title: Recipes --- -_Recipes_ are what we call the configuration file used to deploy apps with our `abra` tool. A longer explanation is in the [glossary](/glossary#recipe). Our _Catalogue_ is a web interface for explore the currently available configurations, therefore which apps can be deployed. +_Recipes_ are what we call the configuration file used to deploy apps with our `abra` CLI tool. A longer explanation is in the [glossary](/glossary#recipe). Our _Catalogue_ is a web interface for exploring the currently available configurations, therefore which apps can be deployed. ### Catalogue @@ -10,7 +10,7 @@ Our catalogue is located at [recipes.coopcloud.tech](https://recipes.coopcloud.t [Browse Our Recipes](https://recipes.coopcloud.tech/){ .md-button .md-button--primary } -The catalogue is a helpful place to understand the status of app recipes, who is taking care of the recipes, and who is maintaining deployed instances of which apps. To understand the various scores on recipes, read further. +The catalogue is a helpful place to easily understand the status of app recipes and the link to the source-code of the recipe. To understand the various scores on recipes, read further. ## Status, Features, Score @@ -84,7 +84,7 @@ Currently, recipe maintainers need to update the scores in this section manually ## Requesting Recipes If you'd like to see a new recipe packaged there are two options for you. First is to contribte one as a _Maintainer_ -The second option is to make a request on the `recipes-wishlist` repository issue tracker. +The second option is to make a request on the [`recipes-wishlist`](https://git.coopcloud.tech/coop-cloud/recipes-wishlist) repository issue tracker. If no one is around to help, you can always take a run at it yourself, go to the [Maintainers](/maintainers/) section to help you on your way. @@ -105,4 +105,3 @@ If no one is around to help, you can always take a run at it yourself, go to the
We've seen nice things happen when the requesters are also willing to take an active role in testing the new recipe. Teaming up with whoever volunteers to help do the packaging is best. -