Skip to content

Commit

Permalink
Rework the documentaiton for pulp_deb 3.0
Browse files Browse the repository at this point in the history
closes #886
closes #867

* The installation docs include pulp-cli-deb, http, and jq
* The feature overview docs are completely reworked
* The workfloww docs are completely reworked
* Examples use pulp-cli-deb by default and http where necessary
* All documentad workflows create structure content by default
  • Loading branch information
quba42 committed Sep 4, 2023
1 parent 524c534 commit 8e0c4bb
Show file tree
Hide file tree
Showing 19 changed files with 683 additions and 753 deletions.
3 changes: 1 addition & 2 deletions .github/workflows/scripts/post_docs_test.sh
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
#!/usr/bin/env bash

export BASE_ADDR=https://pulp:443
export CONTENT_ADDR=https://pulp:443/pulp/content
export PULP_URL=https://pulp:443

cd docs/_scripts/
source setup.sh
Expand Down
1 change: 1 addition & 0 deletions CHANGES/867.doc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Added workflow documentation for creating and using signing services.
1 change: 1 addition & 0 deletions CHANGES/886.doc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Completely reworked the "Feature Overview" and "Workflows" docs with an emphasise on Pulp CLI and structured content.
9 changes: 4 additions & 5 deletions docs/_scripts/setup.sh
100644 → 100755
Original file line number Diff line number Diff line change
@@ -1,24 +1,23 @@
#!/usr/bin/env bash
set -e

export BASE_ADDR=${BASE_ADDR:-http://localhost:24817}
export CONTENT_ADDR=${CONTENT_ADDR:-http://localhost:24816/pulp/content}
export PULP_URL=${PULP_URL:-http://localhost:24817}

# Poll a Pulp task until it is finished.
wait_until_task_finished() {
echo "Polling the task until it has reached a final state."
local task_url=$1
local task_url=${1}
while true
do
local response=$(http $task_url)
local response=$(http ${task_url})
local state=$(echo ${response} | jq -r .state)
case ${state} in
failed|canceled)
echo "Task in final state: ${state}"
exit 1
;;
completed)
echo "$task_url complete."
echo "${task_url} complete."
break
;;
*)
Expand Down
47 changes: 28 additions & 19 deletions docs/_scripts/structured_repo.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,33 +4,42 @@ set -ev

trap "rm frigg_1.0_ppc64.deb" EXIT

# user defined values
NAME=manual-upload-frigg-ppc64
DIST=pulp
COMP=upload

RELEASE_FILE_FIELDS=(
codename=${DIST}
suite=${DIST}
version=1
origin=myorigin
label=mylabel
description=mydescription
)

# download a package
wget https://fixtures.pulpproject.org/debian/pool/asgard/f/frigg/frigg_1.0_ppc64.deb

# upload the package
TASK_HREF=$(http --form $BASE_ADDR/pulp/api/v3/content/deb/packages/ file@frigg_1.0_ppc64.deb | jq -r .task)
wait_until_task_finished $BASE_ADDR$TASK_HREF
PACKAGE_HREF=$(http ${BASE_ADDR}${TASK_HREF} | jq -r ".created_resources[0]")

# create a repo and distribution
REPO_HREF=$(http ${BASE_ADDR}/pulp/api/v3/repositories/deb/apt/ name=myrepo | jq -r .pulp_href)
TASK_HREF=$(http ${BASE_ADDR}/pulp/api/v3/distributions/deb/apt/ name=myrepo base_path=myrepo repository=$REPO_HREF | jq -r .task)
wait_until_task_finished $BASE_ADDR$TASK_HREF
REPO_HREF=$(http ${PULP_URL}/pulp/api/v3/repositories/deb/apt/ name=${NAME} | jq -r .pulp_href)
TASK_HREF=$(http ${PULP_URL}/pulp/api/v3/distributions/deb/apt/ name=${NAME} base_path=${NAME} repository=${REPO_HREF} | jq -r .task)
wait_until_task_finished ${PULP_URL}${TASK_HREF}

# upload the package to create Package, ReleaseComponent, PackageReleaseComponent, and Architecture content and add it to the repo in a single action
TASK_HREF=$(http --form ${PULP_URL}/pulp/api/v3/content/deb/packages/ file@frigg_1.0_ppc64.deb repository=${REPO_HREF} distribution=${DIST} component=${COMP} | jq -r .task)
wait_until_task_finished ${PULP_URL}${TASK_HREF}

# create the necessary content (release, comp, architecture)
RELEASE_HREF=$(http ${BASE_ADDR}/pulp/api/v3/content/deb/releases/ distribution=mydist codename=mycodename suite=mysuite | jq -r .pulp_href)
# Note that creating the release is optional, but without it your published repo will use default values for the suite and the codename in the published Release file.
ARCH_HREF=$(http ${BASE_ADDR}/pulp/api/v3/content/deb/release_architectures/ distribution=mydist architecture=ppc64 | jq -r .pulp_href)
COMP_HREF=$(http ${BASE_ADDR}/pulp/api/v3/content/deb/release_components/ distribution=mydist component=mycomp | jq -r .pulp_href)
PKG_COMP_HREF=$(http ${BASE_ADDR}/pulp/api/v3/content/deb/package_release_components/ package=$PACKAGE_HREF release_component=$COMP_HREF | jq -r .pulp_href)
# Also create a Release content to set various release file fields
RELEASE_HREF=$(http ${PULP_URL}/pulp/api/v3/content/deb/releases/ distribution=${DIST} ${RELEASE_FILE_FIELDS[@]} | jq -r .pulp_href)

# add our content to the repository
TASK_HREF=$(http ${BASE_ADDR}${REPO_HREF}modify/ add_content_units:="[\"$RELEASE_HREF\", \"$COMP_HREF\", \"$PACKAGE_HREF\", \"$PKG_COMP_HREF\", \"$ARCH_HREF\"]" | jq -r .task)
wait_until_task_finished $BASE_ADDR$TASK_HREF
TASK_HREF=$(http ${PULP_URL}${REPO_HREF}modify/ add_content_units:="[\"${RELEASE_HREF}\"]" | jq -r .task)
wait_until_task_finished ${PULP_URL}${TASK_HREF}

# publish our repo
TASK_HREF=$(http ${BASE_ADDR}/pulp/api/v3/publications/deb/apt/ repository=$REPO_HREF structured=true | jq -r .task)
wait_until_task_finished $BASE_ADDR$TASK_HREF
TASK_HREF=$(http ${PULP_URL}/pulp/api/v3/publications/deb/apt/ repository=${REPO_HREF} | jq -r .task)
wait_until_task_finished ${PULP_URL}${TASK_HREF}

# check that our repo has one of the package index folders we would expect
http --check-status ${CONTENT_ADDR}/myrepo/dists/mydist/mycomp/binary-ppc64/
http --check-status ${PULP_URL}/pulp/content/${NAME}/dists/${DIST}/${COMP}/binary-ppc64/Packages
18 changes: 15 additions & 3 deletions docs/external_references.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
.. _pulpcore documentation:
https://docs.pulpproject.org/pulpcore/
.. _pulpcore configuration documentation:
https://docs.pulpproject.org/pulpcore/installation/configuration.html
https://docs.pulpproject.org/pulpcore/configuration/index.html
.. _pulpcore installation options:
https://docs.pulpproject.org/pulpcore/installation/index.html
.. _pulpcore plugin API deprecation policy:
https://docs.pulpproject.org/pulpcore/plugins/plugin-writer/concepts/index.html#plugin-api-stability-and-deprecation-policy
.. _pulpcore settings documentation:
https://docs.pulpproject.org/pulpcore/settings.html#pulp-settings
https://docs.pulpproject.org/pulpcore/configuration/settings.html#pulp-settings
.. _pulpcore import-export docs:
https://docs.pulpproject.org/pulpcore/workflows/import-export.html
.. _pulpcore metadata signing docs:
Expand Down Expand Up @@ -67,7 +67,9 @@
.. _pulp_deb GitHub actions pipelines:
https://github.com/pulp/pulp_deb/actions
.. _httpie:
https://httpie.org/doc
https://httpie.io/
.. _jq:
https://jqlang.github.io/jq/
.. _nginx.org:
https://nginx.org/en/linux_packages.html#Debian
.. _pulp-cli-deb issue tracker:
Expand All @@ -78,3 +80,13 @@
https://pypi.org/project/pulp-cli/
.. _pulp-cli documentation:
https://docs.pulpproject.org/pulp_cli/
.. _import export issue:
https://github.com/pulp/pulp_deb/issues/872
.. _translation file issue:
https://github.com/pulp/pulp_deb/issues/408
.. _dependency solving issue:
https://github.com/pulp/pulp_deb/issues/386
.. _source package PR:
https://github.com/pulp/pulp_deb/pull/295
.. _multi tenancy feature request:
https://github.com/pulp/pulp_deb/issues/860
Loading

0 comments on commit 8e0c4bb

Please sign in to comment.