pulp · dkliban · Jan 31, 2024 · Jan 25, 2024
diff --git 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
@@ -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
@@ -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
@@ -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/<distribution.base_path>`
+
+=== "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
@@ -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
+```