Hey Kevin and Petr (and anyone else on the list who is interested),
I've been talking with Ben Cotton about moving the elections application into Communishift[0]. We had a few back and forth e-mails, and it became clear that it would be helpful if we had quality documentation describing how community members can use Communishift.
I think there may need to be a balance between documenting how to use OpenShift, and linking to already existing resources regarding the use of OpenShift. Perhaps some simple hello world type examples would be good to document, but it would probably be best to link to official OpenShift documentation for details on how to use OpenShift.
On the other hand, there are likely to be some particularities with how we have deployed/configured Communishift that should be documented. Since we are hoping to hand off several infrastructure applications to the community, there may be some common patterns among those apps that would be good to document as well.
It would also be good to document best practices suggestions for some common problems our users will need to solve:
* How can they use persistent storage? * How can they use a database? * How can they back up the applications, persistent storage, and database?
We do have a wiki page[1] for Communishift already that we can use as a starting point, but we probably want to move it to our documentation project as we extend it.
Let me know if you are interested in participating in this project.
[0] Communishift is an OpenShift instance hosted by Fedora Infrastructure for the community to use to host applications for Fedora. Fedora Infrastructure does not maintain or administrate any applications in Communishift, but rather administers the OpenShift deployment itself. [1] https://fedoraproject.org/wiki/Infrastructure/Communishift
Randy,
Thanks for starting this conversation. +1 to moar docs, +1 to linking to the OpenShift docs where we can, +1 to putting it on docs.fp.o. The target audience will be people who have some degree of technical expertise but may not have any experience with OpenShift and many not interact with it much.
As I work with the Infra team to move the Elections app, I plan on taking copious notes, and I am happy to help convert that into some content for the docs.
On Mon, Sep 23, 2019 at 11:27:44AM -0400, Ben Cotton wrote:
Randy,
Thanks for starting this conversation. +1 to moar docs, +1 to linking to the OpenShift docs where we can, +1 to putting it on docs.fp.o. The target audience will be people who have some degree of technical expertise but may not have any experience with OpenShift and many not interact with it much.
I've created the project: https://pagure.io/infra-docs-fpo which is aimed at moving our contributors/users facing doc from the wiki to docs.fp.o We could easily leverage this project to put the communyshift docs if people think it's a good idea :)
Pierre
On Mon, Sep 23, 2019 at 11:16:04AM -0400, Randy Barlow wrote:
Hey Kevin and Petr (and anyone else on the list who is interested),
I've been talking with Ben Cotton about moving the elections application into Communishift[0]. We had a few back and forth e-mails, and it became clear that it would be helpful if we had quality documentation describing how community members can use Communishift.
+10
I think there may need to be a balance between documenting how to use OpenShift, and linking to already existing resources regarding the use of OpenShift. Perhaps some simple hello world type examples would be good to document, but it would probably be best to link to official OpenShift documentation for details on how to use OpenShift.
Yeah, there's tons of docs out there about using openshift and how to get started, etc. We shouldn't document any of that, but pointing to some good ones sounds like a great idea.
On the other hand, there are likely to be some particularities with how we have deployed/configured Communishift that should be documented. Since we are hoping to hand off several infrastructure applications to the community, there may be some common patterns among those apps that would be good to document as well.
Yep.
It would also be good to document best practices suggestions for some common problems our users will need to solve:
- How can they use persistent storage?
Just make a pvc (persistent volume claim) and it will get filled. We use NFS, but I'm not sure they need to know that.
One thing we still need to sort out though is that we currently have a bunch of nfs volumes defined for pv's, but to be safe we have set them to 'reclaim', which means when someone uses one, then stops using it, the volume needs to be wiped and re-added. This means that we run out of pv's after a while as they are used. We either need to automate something reclaiming them or some other solution so we don't have to manually clean them up. (sorry for the side note)
- How can they use a database?
They need to make a db pod and use a persistent volume. We could make this easier perhaps by installing some database operators.
- How can they back up the applications, persistent storage, and database?
oc get --export all -o json for the storage, perhaps rsync or tar with oc rsh ditto the database.
We do have a wiki page[1] for Communishift already that we can use as a starting point, but we probably want to move it to our documentation project as we extend it.
Sure. I just put it there because it was easy.
Let me know if you are interested in participating in this project.
Happy to help out.
kevin --
[0] Communishift is an OpenShift instance hosted by Fedora Infrastructure for the community to use to host applications for Fedora. Fedora Infrastructure does not maintain or administrate any applications in Communishift, but rather administers the OpenShift deployment itself. [1] https://fedoraproject.org/wiki/Infrastructure/Communishift
On Mon, Sep 23, 2019 at 12:18:08PM -0700, Kevin Fenzi wrote:
- How can they use persistent storage?
Just make a pvc (persistent volume claim) and it will get filled. We use NFS, but I'm not sure they need to know that.
One thing we still need to sort out though is that we currently have a bunch of nfs volumes defined for pv's, but to be safe we have set them to 'reclaim', which means when someone uses one, then stops using it, the volume needs to be wiped and re-added. This means that we run out of pv's after a while as they are used. We either need to automate something reclaiming them or some other solution so we don't have to manually clean them up. (sorry for the side note)
On my k8s cluster I'm using nfs-client-provisioner: https://github.com/kubernetes-incubator/external-storage/tree/master/nfs-cli...
Hi,
On 9/23/19 5:16 PM, Randy Barlow wrote:
Hey Kevin and Petr (and anyone else on the list who is interested),
I've been talking with Ben Cotton about moving the elections application into Communishift[0]. We had a few back and forth e-mails, and it became clear that it would be helpful if we had quality documentation describing how community members can use Communishift.
I think there may need to be a balance between documenting how to use OpenShift, and linking to already existing resources regarding the use of OpenShift. Perhaps some simple hello world type examples would be good to document, but it would probably be best to link to official OpenShift documentation for details on how to use OpenShift.
On the other hand, there are likely to be some particularities with how we have deployed/configured Communishift that should be documented. Since we are hoping to hand off several infrastructure applications to the community, there may be some common patterns among those apps that would be good to document as well.
Yeah, that sounds reasonable. I did something similar with the Taiga docs that I wrote up some months ago (and that ended up unused :). They generally focus on things that are specific to Fedora, and link to the full Taiga documentation elsewhere for those who want more details. It's a good approach to take when there's upstream documentation available.
It would also be good to document best practices suggestions for some common problems our users will need to solve:
- How can they use persistent storage?
- How can they use a database?
- How can they back up the applications, persistent storage, and database?
We do have a wiki page[1] for Communishift already that we can use as a starting point, but we probably want to move it to our documentation project as we extend it.
Let me know if you are interested in participating in this project.
Sure! You guys are the experts and you know all about what people need to do and how to do it, so it's best if you do most of the actual content writing; I'm happy to help you with markup, structure and that sort of stuff. Some basic info about how the docs site works is in the template repo README: https://pagure.io/fedora-docs/template
Once we have something publishable I'll add it to the site and link it from https://docs.fedoraproject.org/en-US/engineering/
[0] Communishift is an OpenShift instance hosted by Fedora Infrastructure for the community to use to host applications for Fedora. Fedora Infrastructure does not maintain or administrate any applications in Communishift, but rather administers the OpenShift deployment itself. [1] https://fedoraproject.org/wiki/Infrastructure/Communishift
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/infrastructure@lists.fedorapro...
On Tue, 2019-09-24 at 15:20 +0200, Petr Bokoc wrote:
Sure! You guys are the experts and you know all about what people need to do and how to do it, so it's best if you do most of the actual content writing; I'm happy to help you with markup, structure and that sort of stuff. Some basic info about how the docs site works is in the template repo README: https://pagure.io/fedora-docs/template
Once we have something publishable I'll add it to the site and link it from https://docs.fedoraproject.org/en-US/engineering/
Great!
Do you have a suggestion for a particular git repository to be used for this, or should we start a new git repository just for these docs?
On Tue, 2019-09-24 at 16:55 -0400, Randy Barlow wrote:
On Tue, 2019-09-24 at 15:20 +0200, Petr Bokoc wrote:
Sure! You guys are the experts and you know all about what people need to do and how to do it, so it's best if you do most of the actual content writing; I'm happy to help you with markup, structure and that sort of stuff. Some basic info about how the docs site works is in the template repo README: https://pagure.io/fedora-docs/template
Once we have something publishable I'll add it to the site and link it from https://docs.fedoraproject.org/en-US/engineering/
Great!
Do you have a suggestion for a particular git repository to be used for this, or should we start a new git repository just for these docs?
Or do you recommend using the repo that pingou suggested: https://pagure.io/infra-docs-fpo
On 9/24/19 11:06 PM, Randy Barlow wrote:
On Tue, 2019-09-24 at 16:55 -0400, Randy Barlow wrote:
On Tue, 2019-09-24 at 15:20 +0200, Petr Bokoc wrote:
Sure! You guys are the experts and you know all about what people need to do and how to do it, so it's best if you do most of the actual content writing; I'm happy to help you with markup, structure and that sort of stuff. Some basic info about how the docs site works is in the template repo README: https://pagure.io/fedora-docs/template
Once we have something publishable I'll add it to the site and link it from https://docs.fedoraproject.org/en-US/engineering/
Great!
Do you have a suggestion for a particular git repository to be used for this, or should we start a new git repository just for these docs?
Or do you recommend using the repo that pingou suggested: https://pagure.io/infra-docs-fpo
Pingou's repo is OK to use. I created a new module for these docs within it; the table of contents of this module will appear below the main module's navigation. We can easily change that later if we need to. Any sources go into the module's pages/ directory, and don't forget to link them (xref:filename[link text]) in the module's nav.adoc, otherwise they'll be built and available if you have the page URL, but won't be linked in the sidebar. If you want to use any images, put them in assets/images/ and use "image::only-the-filename-without-directories[optional alt text]". Each source file in pages/ needs to start with a level 1 heading ("= Heading", like index.adoc does), otherwise Antora will still build it but all sorts of weird stuff will start happen. If you want to reuse a snippet of text (like, say, have some kind of a warning box in multiple places but stored only in a single source so you can easily edit it once and see the change everywhere), make a modules/communishift/partials/ directory and put .adoc files containing only these reusable snippets in them (no heading on top or anything), and include them in other sources with "include::partial$filename.adoc[]". These partials won't be built as separate pages, Antora ignores them unless they're included somewhere else, so you won't end up with people coming in from google and finding only the snippet. Generally don't worry about markup too much, once you're at least somewhat done I'll go through everything. Cheers, Petr
infrastructure@lists.fedoraproject.org