From ea7d63e1b6ac39d1ad176942fc812d2ce7818f50 Mon Sep 17 00:00:00 2001 From: Lubos Mjachky Date: Wed, 21 Feb 2024 12:13:04 +0100 Subject: [PATCH] Migrate the documentation to staging closes #347 --- CHANGES/347.doc | 2 + pyproject.toml | 1 + staging_docs/user/guides/00-import-commit.md | 94 ++++++++++++++++++ staging_docs/user/guides/01-modify-content.md | 28 ++++++ staging_docs/user/tutorials/00-overview.md | 35 +++++++ .../user/tutorials/01-sync-and-host.md | 99 +++++++++++++++++++ 6 files changed, 259 insertions(+) create mode 100644 CHANGES/347.doc create mode 100644 staging_docs/user/guides/00-import-commit.md create mode 100644 staging_docs/user/guides/01-modify-content.md create mode 100644 staging_docs/user/tutorials/00-overview.md create mode 100644 staging_docs/user/tutorials/01-sync-and-host.md diff --git a/CHANGES/347.doc b/CHANGES/347.doc new file mode 100644 index 00000000..72129d30 --- /dev/null +++ b/CHANGES/347.doc @@ -0,0 +1,2 @@ +Migrated the whole documentation to staging. The documentation should be now consumed from the +unified docs site. diff --git a/pyproject.toml b/pyproject.toml index d9fdead9..e4de7520 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -73,6 +73,7 @@ ignore = [ "dev_requirements.txt", "doc_requirements.txt", "docs/**", + "staging_docs/**", "template_config.yml", ".ci/**", ".github/**", diff --git a/staging_docs/user/guides/00-import-commit.md b/staging_docs/user/guides/00-import-commit.md new file mode 100644 index 00000000..5ff653df --- /dev/null +++ b/staging_docs/user/guides/00-import-commit.md @@ -0,0 +1,94 @@ +# Import Content + +Create a new repository by running: + +```bash +pulp ostree repository create --name fedora-iot +``` + +## Import a Commit + +First, build an image representing one OSTree commit and wait until the process finishes: + +```bash +echo """name = \"fishy-commit\" +description = \"Fishy OSTree commit\" +version = \"0.0.1\" + +[[packages]] +name = \"fish\" +version = \"*\"""" > fishy.toml + +sudo composer-cli blueprints push fishy.toml +sudo composer-cli compose start-ostree fishy-commit fedora-iot-commit --ref fedora/stable/x86_64/iot +sudo composer-cli compose status +``` + +Download the result from the server by issuing: + +```bash +sudo composer-cli compose image ${COMPOSER_TASK_UUID} +``` + +Ensure that the downloaded tarball is readable by Pulp and import it: + +```bash +pulp ostree repository import-all --name fedora-iot --file ${IMAGE_TARBALL_C1} --repository_name repo +``` + +!!! note + + The argument `repository_name` describes the name of an OSTree repository that is contained + within the tarball. The name of a repository created by `composer-cli` defaults to `repo`. + + +## Import more Commits + +If there is a need to import additional commits, one can do so by attaching new commits to the last +commit in the existing repository: + +```bash +echo """name = \"vim-commit\" +description = \"Vim OSTree commit\" +version = \"0.0.2\" + +[[packages]] +name = \"vim\" +version = \"*\"""" > vim.toml + +sudo composer-cli blueprints push vim.toml +``` + +!!! note + + Through this step, the reader should have distributed the imported repository to enable the + `composer-cli` utility to download a parent commit to which more commits are going to be + attached. Follow `the publish workflow ` to learn how to distribute a + repository. + + +Set the reference to the parent commit, the URL of a Pulp repository to verify the parent against, +and monitor the status of the build: + +```bash +sudo composer-cli compose start-ostree vim-commit fedora-iot-commit --ref fedora/stable/x86_64/iot --parent fedora/stable/x86_64/iot --url ${DISTRIBUTION_BASE_URL} +sudo composer-cli compose status +``` + +Download the result from the server by issuing: + +```bash +sudo composer-cli compose image ${TASK_UUID} +``` + +Import the downloaded tarball into Pulp: + +```bash +pulp ostree repository import-commits --name fedora-iot --file ${IMAGE_TARBALL_C2} --repository_name repo --ref fedora/stable/x86_64/iot +``` + +!!! note + + The OSTree plugin currently supports only repositories with the modern `archive` format. The + repository's config file still uses the historical term `archive-z2` to signify such a format. + diff --git a/staging_docs/user/guides/01-modify-content.md b/staging_docs/user/guides/01-modify-content.md new file mode 100644 index 00000000..623b6897 --- /dev/null +++ b/staging_docs/user/guides/01-modify-content.md @@ -0,0 +1,28 @@ +# Modify Content + +Users add existing content to a repository by issuing the following commands: + +```bash +pulp ostree repository ref add --repository foo --name ${REF_NAME} --checksum ${COMMIT_CHECKSUM1} +pulp ostree repository commit add --repository foo --checksum ${COMMIT_CHECKSUM2} +pulp ostree repository config add --repository foo --pulp_href ${PULP_HREF_CONFIG} +``` + +The added content can be listed by inspecting the latest repository version: + +```bash +pulp ostree repository ref list --repository foo +pulp ostree repository config list --repository foo --version 1 +``` + +Similarly, to remove content, one specifies refs and commits that should be removed, like so: + +```bash +pulp ostree repository ref remove --repository foo --name ${REF_NAME} --checksum ${COMMIT_CHECKSUM1} +pulp ostree repository commit remove --repository foo --checksum ${COMMIT_CHECKSUM2} +``` + +!!! note + + Bear in mind that the `ostree` utility may require the `config` file to be present in the + published repository as well. Otherwise, the `pull` operations may not be successful. diff --git a/staging_docs/user/tutorials/00-overview.md b/staging_docs/user/tutorials/00-overview.md new file mode 100644 index 00000000..b5200ec1 --- /dev/null +++ b/staging_docs/user/tutorials/00-overview.md @@ -0,0 +1,35 @@ +# Overview + +The Pulp OSTree plugin adds support for managing OSTree repositories. In this section, +readers will learn more about the concept of mirroring remote repositories and publishing +them for further client's consumption. + +## Features + +- **Synchronize** a remote OSTree repository and serve it via Pulp. +- **Import** new OSTree commits to an existing repository. +- **Modify** commits and refs within a published repository. +- **Consume** OSTree content imported to Pulp by leveraging the `ostree` utility. + +## Requirements + +Usually, it is recommended to instal the following utilities when managing OSTree content: + +- [ostree](https://manpages.debian.org/testing/ostree/ostree.1.en.html) - a CLI tool for managing + versioned filesystem trees locally +- [osbuild-composer](https://github.com/osbuild/osbuild-composer) - an HTTP service for building + bootable OS disk images +- [composer-cli](https://osbuild.org/docs/user-guide/introduction) - a tool + for use with a WELDR API server, managing blueprints, or building new images + +In this documentation, these utilities are used to demonstrate the way how to create and consume +the OSTree content as well as how they can complement the Pulp's functionality. + +For the best user experience, the workflows utilize [Pulp CLI OSTree](https://github.com/pulp/pulp-cli-ostree). +Install the CLI for the OSTree plugin and update its configuration if necessary. It is simple! + +```bash +pip install pulp-cli-ostree + +pulp config create && pulp config edit # configure the reference to the running Pulp instance +``` diff --git a/staging_docs/user/tutorials/01-sync-and-host.md b/staging_docs/user/tutorials/01-sync-and-host.md new file mode 100644 index 00000000..27170d62 --- /dev/null +++ b/staging_docs/user/tutorials/01-sync-and-host.md @@ -0,0 +1,99 @@ +# Mirror and Host Content + +In this tutorial, there is demonstrated how one can mirror remote content into a local Pulp +repository. + +Users can populate their repositories with content from external sources by syncing a remote +repository. The procedure is as follows: first, create a repository object, then establish a +remote object pointing to the external source, and finally execute a sync task. Upon completion +of the sync task, the content is ready to be promoted/published and becomes visible to end users. + +## Create a Repository + +Start by creating a new repository named "foo". + +```bash +pulp ostree repository create --name foo +``` + +## Create a Remote + +Then, create a remote object that informs Pulp about an external content source. + +```bash +pulp ostree remote create --name bar --url https://fixtures.pulpproject.org/ostree/small/ +``` + +Optionally, use the standard Linux wildcards `*`, `?` to include or exclude specific commits from +a remote repository. This might be helpful when there is no need to mirror everything from the +remote repository. Besides that, it reduces the network or storage overhead. + +```bash +pulp ostree remote create --name bar-filtered --url https://fixtures.pulpproject.org/ostree/small/ --include-refs "[\"stable\"]" --exclude-refs "[\"raw*\"]" +``` + +## Sync the Repository + +After creating the repository and remote, use these objects to kick off a synchronization task. +This tells Pulp to fetch content from the remote source and add it to the repository. + +```bash +pulp ostree repository sync --name foo --remote bar +``` + +!!! note + + The OSTree plugin currently supports only repositories with the modern `archive` format. The + repository's config file still uses the historical term `archive-z2` to signify such a format. + +## Host Content (Create a Distribution) + +To serve the OSTree content from Pulp, the user needs to create a distribution that will host the +associated repository at `${PULP_BASE_ADDR}/pulp/content/`: + +```bash +pulp ostree distribution create --name fedora-iot --base-path fedora-iot --repository fedora-iot +``` + +The content present in the latest repository version is automatically published and accessible by +package managers (e.g., the `ostree` utility). + + +## Consume the Content + +Now, configure a local OSTree repository to consume the content from the Pulp repository. + +=== "Script" + + ```bash + ostree --repo=repo init --mode=archive + ostree --repo=repo remote --no-gpg-verify add pulpos ${PULP_BASE_ADDR}/pulp/content/fedora-iot + + ostree pull --repo=repo --mirror pulpos:fedora/stable/x86_64/iot --depth=-1 + ostree log --repo=repo fedora/stable/x86_64/iot + ``` + +=== "Output" + + ``` + commit 9bbeb2f9961b425b70551b91992e4e3169e7c695f93d99b03e3f2aac463231bf + Parent: 50aeff7f74c66041ffc9e197887bfd5e427248ff1405e0e61e2cff4d3a1cecc7 + ContentChecksum: 237941566711d062b8b73d0c2823225d59c404d78bf184243c6031fa279e8a1f + Date: 2021-09-06 15:48:13 +0000 + (no subject) + + commit 50aeff7f74c66041ffc9e197887bfd5e427248ff1405e0e61e2cff4d3a1cecc7 + ContentChecksum: 10155b85154b87675970fd56c4a3b44c4739b486772926ed7463f1c827e7a236 + Date: 2021-09-06 11:35:16 +0000 + (no subject) + ``` + +!!! note + + The plugin automatically generates static deltas for a specific subset of commits. Currently, + the summary file is not being updated after every single change to the repository. + +Users are allowed to copy and remove content within repositories. When a new ref is being added or +removed from a repository, all the referenced commits and file objects will be added or removed as +well in order to preserve the integrity of the repository. Visit the guide section to learn more +about particular workflows.