Skip to content

Commit

Permalink
Migrate content to staging_docs
Browse files Browse the repository at this point in the history 
- Convert content to markdown
- Clean and apply mkdocs style features

[noissue]
  • Loading branch information
@pedro-psb
pedro-psb committed Jan 29, 2024
1 parent 4de8c2a commit 9aa5d57
Show file tree
Hide file tree
Showing 5 changed files with 343 additions and 0 deletions.
1 change: 1 addition & 0 deletions pyproject.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ ignore = [
"dev_requirements.txt",
"doc_requirements.txt",
"docs/**",
"staging_docs/**",
"template_config.yml",
".travis/**",
".travis.yml",
Expand Down
92 changes: 92 additions & 0 deletions staging_docs/user/guides/01-upload.md
View file
Original file line number Diff line number Diff line change
@@ -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/"
}
}
}
}
```
113 changes: 113 additions & 0 deletions staging_docs/user/guides/02-sync.md
View file
Original file line number Diff line number Diff line change
@@ -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/"
}
}
}
}
```

90 changes: 90 additions & 0 deletions staging_docs/user/guides/03-publish.md
View file
Original file line number Diff line number Diff line change
@@ -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
```
47 changes: 47 additions & 0 deletions staging_docs/user/tutorials/quickstart.md
View file
Original file line number Diff line number Diff line change
@@ -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
```

0 comments on commit 9aa5d57

Please sign in to comment.