Reduce UI clutter & improve Recipes
- Remove word ___ Guide from various pages - Camel Case titles - Move Recipes sub-page of Abra
This commit is contained in:
parent
f919f0c10b
commit
b5afd99f66
|
|
@ -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/):
|
||||
|
||||
```
|
||||
<!-- metadata -->
|
||||
|
||||
* **Category**: Apps
|
||||
* **Status**: 3, stable
|
||||
* **Image**: [`wordpress`](https://hub.docker.com/_/wordpress), 4, upstream
|
||||
* **Healthcheck**: Yes
|
||||
* **Backups**: Yes
|
||||
* **Email**: 3
|
||||
* **Tests**: 2
|
||||
* **SSO**: No
|
||||
|
||||
<!-- endmetadata -->
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- __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 }
|
||||
|
||||
</div>
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- __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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- __Organisers handbook__
|
||||
- __Organisers Handbook__
|
||||
|
||||
One-stop shop for all you need to know to organise in the community :sparkles:
|
||||
|
||||
|
|
|
|||
|
|
@ -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/):
|
||||
|
||||
```
|
||||
<!-- metadata -->
|
||||
|
||||
* **Category**: Apps
|
||||
* **Status**: 3, stable
|
||||
* **Image**: [`wordpress`](https://hub.docker.com/_/wordpress), 4, upstream
|
||||
* **Healthcheck**: Yes
|
||||
* **Backups**: Yes
|
||||
* **Email**: 3
|
||||
* **Tests**: 2
|
||||
* **SSO**: No
|
||||
|
||||
<!-- endmetadata -->
|
||||
```
|
||||
|
||||
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.
|
||||
|
|
@ -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;
|
||||
}
|
||||
|
|
|
|||
38
mkdocs.yml
38
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue