From e756b8dcaa151a5896c753839a2409ad6a3a45ac Mon Sep 17 00:00:00 2001 From: Pedro Brochado Date: Thu, 25 Jan 2024 17:00:38 -0300 Subject: [PATCH] Migrate content to staging_docs - Convert content to markdown - Clean and apply mkdocs style features [noissue] --- pyproject.toml | 1 + staging_docs/user/guides/01-upload.md | 92 ++++++++++++++++++ staging_docs/user/guides/02-sync.md | 113 ++++++++++++++++++++++ staging_docs/user/guides/03-publish.md | 90 +++++++++++++++++ staging_docs/user/tutorials/quickstart.md | 47 +++++++++ 5 files changed, 343 insertions(+) create mode 100644 staging_docs/user/guides/01-upload.md create mode 100644 staging_docs/user/guides/02-sync.md create mode 100644 staging_docs/user/guides/03-publish.md create mode 100644 staging_docs/user/tutorials/quickstart.md diff --git a/pyproject.toml b/pyproject.toml index f533d3a5..85644650 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,6 +34,7 @@ ignore = [ "dev_requirements.txt", "doc_requirements.txt", "docs/**", + "staging_docs/**", "template_config.yml", ".travis/**", ".travis.yml", diff --git a/staging_docs/user/guides/01-upload.md b/staging_docs/user/guides/01-upload.md new file mode 100644 index 00000000..fd255ef1 --- /dev/null +++ b/staging_docs/user/guides/01-upload.md @@ -0,0 +1,92 @@ +# Upload and Manage Content + +## 1. Create a Repository + +Start by creating a new repository named "foo". + +=== "run" + ```bash + pulp gem repository create --name foo + ``` +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/", + "pulp_created": "2023-06-22T20:54:27.113947Z", + "versions_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/", + "pulp_labels": {}, + "latest_version_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/0/", + "name": "foo", + "description": null, + "retain_repo_versions": null, + "remote": null + } + ``` + +## 2. Upload a file to Pulp + +Each artifact in Pulp represents a file. They can be created during sync or created manually by uploading a file + +=== "run" + ```bash + # Get a Gem package or choose your own and upload to Pulp + curl -O https://fixtures.pulpproject.org/gem/gems/amber-1.0.0.gem + pulp gem content upload --file "amber-1.0.0.gem" + CONTENT_HREF=$(pulp gem content list | jq -r .[0].pulp_href) + ``` +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/content/gem/gem/0188e53f-b8ae-71e8-a2da-a1c79ab9d822/", + "pulp_created": "2023-06-22T22:35:38.543295Z", + "artifacts": { + "gems/amber-1.0.0.gem": "/pulp/api/v3/artifacts/0188e53f-b84e-74c9-a82e-60583c0e4fd2/", + "quick/Marshal.4.8/amber-1.0.0.gemspec.rz": "/pulp/api/v3/artifacts/0188e53f-b8aa-7d05-8dd2-1b941fef9b6e/" + }, + "name": "amber", + "version": "1.0.0", + "prerelease": false, + "dependencies": {}, + "required_ruby_version": ">= 0", + "required_rubygems_version": ">= 0" + } + ``` + +!!! note + You can also specify a repository during an upload to immediately add the uploaded content to the repository. + +## 3. Add content to a repository + +Once there is a content unit, it can be added and removed from repositories using the add and remove commands. +This will create a new `repository version`. + +=== "run" + ```bash + pulp gem repository content add --repository foo --href $CONTENT_HREF + pulp gem repository version show --repository foo + ``` +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/2/", + "pulp_created": "2023-06-22T22:54:09.911372Z", + "number": 2, + "repository": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/", + "base_version": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/1/", + "content_summary": { + "added": { + "gem.gem": { + "count": 1, + "href": "/pulp/api/v3/content/gem/gem/?repository_version_added=/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/2/" + } + }, + "removed": {}, + "present": { + "gem.gem": { + "count": 34, + "href": "/pulp/api/v3/content/gem/gem/?repository_version=/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/2/" + } + } + } + } + ``` diff --git a/staging_docs/user/guides/02-sync.md b/staging_docs/user/guides/02-sync.md new file mode 100644 index 00000000..5ad5598a --- /dev/null +++ b/staging_docs/user/guides/02-sync.md @@ -0,0 +1,113 @@ +# Synchronize a Repository + +Users can populate their repositories with content from an external sources by syncing +their repository. + +## 1. Create a Repository + +Start by creating a new repository named "foo" + +=== "run" + ```bash + pulp gem repository create --name foo + ``` +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/", + "pulp_created": "2023-06-22T20:54:27.113947Z", + "versions_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/", + "pulp_labels": {}, + "latest_version_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/0/", + "name": "foo", + "description": null, + "retain_repo_versions": null, + "remote": null + } + ``` + +## 2. Create a Remote + +Create a remote that syncs all versions of panda into your repository. + +=== "run" + ```bash + pulp gem remote create --name gem --url https://index.rubygems.org/ --includes '{"panda":null}' + ``` + !!! note + You can also not specify anything in `includes` and have Pulp try to sync all gems available on the remote. + + `includes` and `excludes` fields are JSON dictionaries with the key being the gem name and the value being the version specifier string, or `null` for syncing all versions. + +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/remotes/gem/gem/0188e505-157c-7565-8474-e607e0dbc4a0/", + "pulp_created": "2023-06-22T21:31:35.676442Z", + "name": "gem", + "url": "https://index.rubygems.org", + "ca_cert": null, + "client_cert": null, + "tls_validation": true, + "proxy_url": null, + "pulp_labels": {}, + "pulp_last_updated": "2023-06-22T21:31:35.676454Z", + "download_concurrency": null, + "max_retries": null, + "policy": "immediate", + "total_timeout": null, + "connect_timeout": null, + "sock_connect_timeout": null, + "sock_read_timeout": null, + "headers": null, + "rate_limit": null, + "hidden_fields": [...], + "prereleases": false, + "includes": { + "panda": null + }, + "excludes": null + } + ``` + + +## 3. Sync repository foo with remote + +Use the remote object to kick off a synchronize task by specifying the repository to sync with. +You are telling pulp to fetch content from the remote and add to the repository + +=== "run" + ```bash + pulp gem repository sync --name foo --remote gem + pulp gem repository version show --repository foo + ``` + !!! note + The `sync` command will by default wait for the sync to complete. + + Use `Ctrl+c` or the `-b` option to send the task to the background. +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/1/", + "pulp_created": "2023-06-22T21:40:00.488466Z", + "number": 1, + "repository": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/", + "base_version": null, + "content_summary": { + "added": { + "gem.gem": { + "count": 33, + "href": "/pulp/api/v3/content/gem/gem/?repository_version_added=/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/1/" + } + }, + "removed": {}, + "present": { + "gem.gem": { + "count": 33, + "href": "/pulp/api/v3/content/gem/gem/?repository_version=/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/1/" + } + } + } + } + ``` + diff --git a/staging_docs/user/guides/03-publish.md b/staging_docs/user/guides/03-publish.md new file mode 100644 index 00000000..1ddd3e82 --- /dev/null +++ b/staging_docs/user/guides/03-publish.md @@ -0,0 +1,90 @@ +# Publish and Host a Repository + +This section assumes that you have a repository with content in it. +See [Sync](site:pulp_gem/docs/user/guides/sync/) or [Upload](site:pulp_gem/docs/user/guides/upload/) guides. + +## 1. Create a Publication + +Kick off a publish task by creating a new publication. The publish task will generate all the +metadata that `gem` needs to install packages (although it will need to be hosted through a +Distribution before it is consumable). + +=== "run" + ```bash + pulp gem publication create --repository foo --version 1 + ``` + + !!! tip + If `--version` is ommited, Pulp will assume the latest version. +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/publications/gem/gem/0188e510-cbbe-7586-b182-927bacc89bdb/", + "pulp_created": "2023-06-22T21:44:23.230932Z", + "repository_version": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/versions/1/", + "repository": "/pulp/api/v3/repositories/gem/gem/0188e4e3-1429-7411-89d7-c87288edf51a/" + } + ``` + + +## 2. Host a Publication by creating a Distribution + +To host a publication, (which makes it consumable by `gem`), users create a distribution which will serve the associated publication at `/pulp/content/` + +=== "run" + ```bash + PUBLICATION_HREF=$(pulp gem publication list | jq -r .[0].pulp_href) + pulp gem distribution create --name foo \ + --base-path foo --publication "$PUBLICATION_HREF" + ``` +=== "output" + ```json + { + "pulp_href": "/pulp/api/v3/distributions/gem/gem/0188e513-594c-7c44-aaff-beed0f97363e/", + "pulp_created": "2023-06-22T21:47:10.540670Z", + "base_path": "foo", + "base_url": "http://localhost:5001/pulp/content/foo/", + "content_guard": null, + "hidden": false, + "pulp_labels": {}, + "name": "foo", + "repository": null, + "publication": "/pulp/api/v3/publications/gem/gem/0188e510-cbbe-7586-b182-927bacc89bdb/", + "remote": null + } + ``` + +!!! note + Alternatively you could specify the repository when creating a distribution in which case Pulp will automatically distribute the latest available publication for the greatest repository version + + +## 3. Enable Pull-Through Caching: + +Only gems present in your repository will be available from your index, but adding a remote source to +your distribution will enable the pull-through cache feature. + +This feature allows you to install any gem from the remote source and have Pulp store that gem as orphaned content. + +```bash +pulp gem distribution update --name foo --remote gem +``` + +!!! warning + Support for pull-through caching is provided as a tech preview in Pulp 3. + Functionality may not work or may be incomplete. Also, backwards compatibility when upgrading is not guaranteed. + + +## 4. Use the newly created distribution + +The metadata and packages can now be retrieved from the distribution: + +```bash +http $BASE_ADDR/pulp/content/foo/specs.4.8 +http $BASE_ADDR/pulp/content/foo/gems/panda-1.1.0.gem +``` + +The content is now gem installable: + +``` +gem install --clear-sources --source $BASE_ADDR/pulp/content/foo/ panda +``` diff --git a/staging_docs/user/tutorials/quickstart.md b/staging_docs/user/tutorials/quickstart.md new file mode 100644 index 00000000..753ca9eb --- /dev/null +++ b/staging_docs/user/tutorials/quickstart.md @@ -0,0 +1,47 @@ +# User Setup + +All workflow examples use the Pulp CLI. Install and setup from PyPI: + +```bash +pip install pulp-cli[pygments] pulp-cli-gem +pulp config create -e +pulp status # Check that CLI can talk to Pulp +``` + +If you configured the `admin` user with a different password, adjust the configuration +accordingly. If you prefer to specify the username and password with each request, please see +`Pulp CLI` documentation on how to do that. + +### Install + +=== "Containerized Installation" + + Follow the [Pulp in One Container](https://pulpproject.org/pulp-in-one-container/) instructions to get started with Pulp by + leveraging OCI images. Further details are discussed in the [pulpcore documentation](https://docs.pulpproject.org/pulpcore/installation/instructions.html). + +=== "From Source" + + ```bash + sudo -u pulp -i + source ~/pulp/bin/activate + cd pulp_gem + pip install -e . + django-admin runserver 24817 + ``` + +### Make and Run Migrations + +```bash +pulp-manager makemigrations pulp_gem +pulp-manager migrate pulp_gem +``` + +### Run Services + +```bash +pulp-manager runserver +gunicorn pulpcore.content:server --bind 'localhost:24816' --worker-class 'aiohttp.GunicornWebWorker' -w 2 +sudo systemctl restart pulpcore-resource-manager +sudo systemctl restart pulpcore-worker@1 +sudo systemctl restart pulpcore-worker@2 +```