pulp
As a Pulp user, I want an end-to-end tutorial with all the steps to get an RPM into Pulp
Author: @melcorr (mcorr)
Redmine Issue: 9149, https://pulp.plan.io/issues/9149
I have community feedback from the survey and elsewhere from over five users asking for end-to-end tutorial style RPM docs. From what I've seen of our Pulp community matrix channel, the beginner steps of the post-installation scenario seems to be a challenge.
Perhaps this would be a good opportunity to create some RPM documentation using the Pulp 3 CLI also. Here is a collection of some of the comments.
Digging through the REST API docs and the challenge of figuring out an end-to-end "here's how you get an RPM into Pulp" (or deb or file) was quite a slog.
" RPM( or in general plugin) docs do not have end to end steps for "how do I make a new RPM repository"
" Lack of tutorial style docs, for example: how to mirror Centos."
From: @melcorr (mcorr) Date: 2021-07-27T11:57:06Z
no idea how this got set to container - sorry!
From: @ggainey (ggainey) Date: 2021-12-13T18:45:51Z
This is related to https://pulp.plan.io/issues/9259 , "workflow-docs should use pulp-cli instead of httpie" , which I am working on right now.
Part of that process has been providing pulp-cli versions of the workflow-scripts described at https://docs.pulpproject.org/pulp_rpm/workflows/scripting.html . For the "get an RPM into pulp", this existing script:
https://github.com/pulp/pulp_rpm/blob/main/docs/_scripts/docs_check_upload.sh
walks through the entire process, including creating a Package and an Advisory and adding them to Pulp and then to a Repository.
The docs_check_* bash-scripts in the _scripts directory don't remove the need for the work/tutorials described in this issue. But they are a place for users to look, for examples of how-to do things!
copying over some notes from a duplicate issue
As a 7 months-old user of pulp, I can tell that, yes, docs are confusing, specially in the beginning. You start playing with pulp, checking the docs, APIs, going back and forth to them + Postman .. kind of frustrating until you get it 😓 Also, is there an easy way to check older versions of the API on readthedocs? i.e.: we're still using 3.17 but currently online docs/API specs are for 3.19
The upload doc doesn't mention the pulp rpm content upload command. Instead, it has users go through the painful process of creating an artifact and then a package.
Lots of the samples don't make sense like the pulp-cli example for creating a repo here exports a $REPO_HREF var (why?)
About the Upload Content, I've opened another issue here https://github.com/pulp/pulp_rpm/issues/3482.
About the end-to-end tutorial, I believe we have a better material now (this one) than we had at the time of this report. Nevertheless, there are some things that could be improved.
Some notes:
-
Create Remote has too many branches
- "normal", with Certs, SLES+12, ULN.
- these could be their own howto "Setup Remotes", since there are all these variants.
- Sync step also provides too many options. They are more briefly described, but they could be better developed in a dedicated howto.
- Some Repository API options is duplicated there. The source of true for this information should be the Rest API docs itself, so probably a link would work.
- Maybe we should consider adding more human friendly descriptions to each endpoints there, I miss some overview descriptions in the API docs.
- Even though this particular page provides a wider range of steps, it lacks a story/project kind of approach. The idea of Mirroring CentOs is an interesting starting point.
- An example of story we might define and can help shape this end-to-end tutorial:
"On this tutorial, we'll learn to use Pulp to manage Rpm repositories. On the first part, we will create a basic setup and learn how we can create our first repository based on CentOs (we can explore both syncing and uploading here). On the second part, we will learn how you can corrupt a publication by messing with the dependencies and then learn about Pulp's poweful way of handling versions and rollbacks. Finally, ...?" - If we came up with a good story of this kind that covers the basic grounds a beginner has to walk through, writing the tutorial will probably be easy.
- An example of story we might define and can help shape this end-to-end tutorial:
Here is a draft of a possible story which covers some core topics, such as populating repos (upload/sync), modifying repos content (modify API) and publishing/distributing content.
Let me know what you think.