diff --git a/docs/client_libraries/overview.mdx b/docs/client_libraries/overview.mdx index c0e29563..e004d30b 100644 --- a/docs/client_libraries/overview.mdx +++ b/docs/client_libraries/overview.mdx @@ -10,7 +10,7 @@ sidebar_position: 0 The following languages are currently supported: - [Go](./go.mdx) -- [Python](https://oras-project.github.io/oras-py/getting_started/user-guide.html) +- [Python](https://oras-project.github.io/oras-py/getting_started/user-guide.html) - [Rust](./rust.mdx) (in progress) ## Unified Experience diff --git a/docs/community/contributing_guide.mdx b/docs/community/contributing_guide.mdx index cef742d4..4c1cc4b8 100644 --- a/docs/community/contributing_guide.mdx +++ b/docs/community/contributing_guide.mdx @@ -148,7 +148,7 @@ Git has a `-s` command line option to do this automatically: If you forgot to do this and have not yet pushed your changes to the remote repository, you can amend your commit with the sign-off by running - git commit --amend -s + git commit --amend -s ## Pull Request Checklist diff --git a/docs/community/contributor_ladder.mdx b/docs/community/contributor_ladder.mdx index d00bc706..3d9cf5ab 100644 --- a/docs/community/contributor_ladder.mdx +++ b/docs/community/contributor_ladder.mdx @@ -16,21 +16,21 @@ sidebar_position: 40 ## Contributor Ladder -Hello! We are excited that you want to learn more about our project contributor ladder! -This contributor ladder outlines the different contributor roles within the project, -along with the responsibilities and privileges that come with them. +Hello! We are excited that you want to learn more about our project contributor ladder! +This contributor ladder outlines the different contributor roles within the project, +along with the responsibilities and privileges that come with them. Community members generally start at the first levels of the "ladder" and advance up it as their involvement in the project grows. Our project members are happy to help you advance along the contributor ladder. -Each of the contributor roles below is organized into three sections. -"Responsibilities" are tasks that a contributor is expected to do. -"Requirements" are qualifications a person needs to meet to be in that role, +Each of the contributor roles below is organized into three sections. +"Responsibilities" are tasks that a contributor is expected to do. +"Requirements" are qualifications a person needs to meet to be in that role, and "Privileges" are rights contributors on that level are entitled to. ### Contributor -A Contributor directly adds value to the project. -Contributions need not be code. -Individuals at the Contributor level may be new contributors, +A Contributor directly adds value to the project. +Contributions need not be code. +Individuals at the Contributor level may be new contributors, or they may only contribute occasionally. * Responsibilities include: @@ -54,22 +54,22 @@ or they may only contribute occasionally. ### Owners Structure There are two types of owners in the ORAS project hierarchy: organization owners and subproject owners. -ORAS organization owners oversee the overall project and its health. -Subproject owners focus on a single repository, -a group of related repositories, -a service (e.g., a website), +ORAS organization owners oversee the overall project and its health. +Subproject owners focus on a single repository, +a group of related repositories, +a service (e.g., a website), or subproject to support the other subprojects (e.g., marketing or community management). -Changes in ORAS Organization owners have to be announced via an -[issue on the Community repository](https://github.com/oras-project/community/issues). +Changes in ORAS Organization owners have to be announced via an +[issue on the Community repository](https://github.com/oras-project/community/issues). Changes to sub-project owners are to be announced via the appropriate sub-project issue. -You can find more information on the roles of organization owners and +You can find more information on the roles of organization owners and subproject owners in the [governance](https://github.com/oras-project/community/blob/main/governance/GOVERNANCE.md). ## Inactivity -It is important for contributors to be and stay active to set an example and show commitment to the project. -Inactivity is harmful to the project as it may lead to unexpected delays, +It is important for contributors to be and stay active to set an example and show commitment to the project. +Inactivity is harmful to the project as it may lead to unexpected delays, contributor attrition, and a lost of trust in the project. * Inactivity is measured by: @@ -81,24 +81,24 @@ contributor attrition, and a lost of trust in the project. ## Involuntary Removal or Demotion -Involuntary removal/demotion of a contributor happens when responsibilities and requirements aren't being met. -This may include repeated patterns of inactivity, extended period of inactivity, -a period of failing to meet the requirements of your role, -and/or a violation of the Code of Conduct. -This process is important because it protects the community and its deliverables while also opens up opportunities for new +Involuntary removal/demotion of a contributor happens when responsibilities and requirements aren't being met. +This may include repeated patterns of inactivity, extended period of inactivity, +a period of failing to meet the requirements of your role, +and/or a violation of the Code of Conduct. +This process is important because it protects the community and its deliverables while also opens up opportunities for new contributors to step in. Involuntary removal or demotion is handled through a vote by a majority of the current Maintainers. ## Stepping Down/Emeritus Process -If and when contributors' commitment levels change, -contributors can consider stepping down (moving down the contributor ladder) vs moving to emeritus status +If and when contributors' commitment levels change, +contributors can consider stepping down (moving down the contributor ladder) vs moving to emeritus status (completely stepping away from the project). -Contact the Maintainers about changing to Emeritus status, +Contact the Maintainers about changing to Emeritus status, or reducing your contributor level. ## Contact -* For inquiries, please drop a message in the #oras channel in the CNCF Workspace. -You can follow the instructions in the [community resources](../community/community_resources.mdx#joining-the-slack-channel) +* For inquiries, please drop a message in the #oras channel in the CNCF Workspace. +You can follow the instructions in the [community resources](../community/community_resources.mdx#joining-the-slack-channel) to join it. \ No newline at end of file diff --git a/docs/community/reporting_security_concerns.mdx b/docs/community/reporting_security_concerns.mdx index 3a8bec81..a3afe2d9 100644 --- a/docs/community/reporting_security_concerns.mdx +++ b/docs/community/reporting_security_concerns.mdx @@ -5,7 +5,7 @@ sidebar_position: 50 # Security Policy -Thank you for taking the time to report a security vulnerability. +Thank you for taking the time to report a security vulnerability. We would like to investigate every report thoroughly. ## Reporting a Vulnerability @@ -22,7 +22,7 @@ Click on `Security` and then `Report a vulnerability` ![Screenshot of how to report a vulnerability](../../static/img/reporting_a_security_concern.png) -**Step 3** +**Step 3** You can fill in all the details of the vulnerability and click on `Submit report`. This report will be visible to only the maintainers (and anyone else required to look into the issue). @@ -40,16 +40,16 @@ Please send us a report whenever you: The ORAS maintainers will acknowledge and analyze your report within 14 working days for high severity issues. -Any vulnerability information you share with us, stays with the maintainers. +Any vulnerability information you share with us, stays with the maintainers. We will only disclose the information that is required to resolve the problem. We will update you on the status of the report throughout. ## Fixing the issue -Once a security vulnerability has been identified, the maintainers (contributors, if required) will work on finding a solution. +Once a security vulnerability has been identified, the maintainers (contributors, if required) will work on finding a solution. The development and testing for the fix will happen in a private GitHub repository in order to prevent premature disclosure of the vulnerability. -After the fix has been tested and deemed fit to be made public, -the changes will be merged from the private GitHub repository to the appropriate public branches. +After the fix has been tested and deemed fit to be made public, +the changes will be merged from the private GitHub repository to the appropriate public branches. All the necessary binaries will be built and published. diff --git a/docs/compatible_oci_registries.mdx b/docs/compatible_oci_registries.mdx index 7ea92fb0..0f230fe5 100644 --- a/docs/compatible_oci_registries.mdx +++ b/docs/compatible_oci_registries.mdx @@ -308,7 +308,7 @@ ACR Artifact Documentation: [aka.ms/acr/artifacts](https://aka.ms/acr/artifacts) - [Authenticating with Zot Registry](https://zotregistry.dev/user-guides/user-guide-datapath/#authentication_2) ``` - echo $ZR_PASSWORD | oras login :5000 -u $ZR_USER --password-stdin + echo $ZR_PASSWORD | oras login :5000 -u $ZR_USER --password-stdin ``` - [Pushing Artifacts to Zot Registry](https://zotregistry.dev/user-guides/user-guide-datapath/#push-an-artifact) diff --git a/docs/concepts/artifact.mdx b/docs/concepts/artifact.mdx index def190a7..f3c9bd56 100644 --- a/docs/concepts/artifact.mdx +++ b/docs/concepts/artifact.mdx @@ -64,7 +64,7 @@ flowchart TD B -->|No| E[type=manifest.config.mediaType] ``` -For artifact authors, the sections below should help deciding on the blob and +For artifact authors, the sections below should help deciding on the blob and config mediaTypes. ## Dissecting the Manifest @@ -110,9 +110,9 @@ in this case the config is an empty blob as per the [empty descriptor guidance][ ### Artifacts with config -Clients have been using the `config.mediaType` property to declare the artifact type. -For OCI artifacts that have a valid config blob the config blob may use its own -mediaType and the `artifactType` property can be set to indicate the type of artifact. +Clients have been using the `config.mediaType` property to declare the artifact type. +For OCI artifacts that have a valid config blob the config blob may use its own +mediaType and the `artifactType` property can be set to indicate the type of artifact. ```json { @@ -136,8 +136,8 @@ mediaType and the `artifactType` property can be set to indicate the type of art #### Prior Art -Before version 1.1 of the [image specification][image-spec], the `config.mediaType` -was used to indicate the type of the artifact. +Before version 1.1 of the [image specification][image-spec], the `config.mediaType` +was used to indicate the type of the artifact. For example the artifact type below for the helm chart is `application/vnd.cncf.helm.config.v1+json` as the manifest does not have the `artifactType` property. @@ -165,7 +165,7 @@ as the manifest does not have the `artifactType` property. Artifacts may store metadata in the manifest as annotations and need not have a config or blobs. For these the `artifactType` property is used to declare the type of the artifact. The config property is required in the manifest and for maximum compatibility -an empty layer is also created as per the [empty descriptors guidance][empty-descriptor]. +an empty layer is also created as per the [empty descriptors guidance][empty-descriptor]. ```json { @@ -191,10 +191,10 @@ an empty layer is also created as per the [empty descriptors guidance][empty-de } ``` -### Artifact authoring decision tree +### Artifact authoring decision tree Putting it all together with the types of artifacts listed above and -[Artifact Guidance in the image specification][artifact-guidelines], the decision tree +[Artifact Guidance in the image specification][artifact-guidelines], the decision tree below should help determine what fields to set when creating an artifact. ```mermaid diff --git a/docs/concepts/reference.mdx b/docs/concepts/reference.mdx index 0fdf1a42..b88934a8 100644 --- a/docs/concepts/reference.mdx +++ b/docs/concepts/reference.mdx @@ -1,6 +1,6 @@ --- title: Reference -sidebar_position: 3 +sidebar_position: 3 --- # Understanding References in the Open Container Initiative (OCI) Standard @@ -30,11 +30,11 @@ This reference is a combination of three parts: 1. **Registry**: This is akin to the home or the server where your images or artifacts are stored. Think of it as the overarching domain. Examples include Docker Hub (docker.io), GitHub Container Registry (ghcr.io), or your own private registry. -2. **Repository**: This is a segment of the reference, after the registry where a particular +2. **Repository**: This is a segment of the reference, after the registry where a particular application or service's images are stored. The repository doesn't necessarily follow a hierarchy within the registry, meaning `a/b/c` and `a/b/c/d` are both valid and distinct repositories, with no implied hierarchy between them. -3. **Tag or Digest**: This is the last part indicating the version of the image or artifact +3. **Tag or Digest**: This is the last part indicating the version of the image or artifact you want to pull or push. #### References by Tag @@ -123,7 +123,7 @@ defaults or shortcuts. For instance, if you were to use docker to pull an image using the reference `nginx`, docker would automatically resolve this to `docker.io/library/nginx:latest`. Here, `docker.io` is the default registry and `library/nginx` is the repository with a 'library' prefix for official images and `latest` is the -default tag. +default tag. ### Conclusion diff --git a/docs/concepts/reftypes.mdx b/docs/concepts/reftypes.mdx index 721f462b..a53b3f77 100644 --- a/docs/concepts/reftypes.mdx +++ b/docs/concepts/reftypes.mdx @@ -38,7 +38,7 @@ create and list reference types. The creation of a reference artifact is a two-step process: - **Step One**: PUT an artifact, say Artifact A, using the PUT Manifest and -blob upload APIs if the artifact has blob content. The prerequisite for a reference +blob upload APIs if the artifact has blob content. The prerequisite for a reference type is that the subject artifact must be known so that it may be added to the subject. - **Step Two**: Put another artifact, say Artifact B, which refers to Artifact A. @@ -62,11 +62,11 @@ reference to Artifact A by specifying the digest of Artifact A as the subject. The association is now established in the registry. :::tip NOTE -The specification does allow pushing the reference artifact **without** requiring -the presense of the the `subject` in the target registry or OCI-Layout. +The specification does allow pushing the reference artifact **without** requiring +the presense of the the `subject` in the target registry or OCI-Layout. ::: -The following example shows the manifest of Artifact B with a reference to Artifact A +The following example shows the manifest of Artifact B with a reference to Artifact A in the `subject` field. ```json @@ -134,7 +134,7 @@ of a certain media type from the registry, which then responds with the filtered The response will include the `OCI-Filters-Applied: artifactType` header to indicate that the response is filtered by the `artifactType` query parameter. -The artifact type is determied by the same rules as per +The artifact type is determied by the same rules as per [OCI artifacts guidlines](artifact.mdx#determining-the-artifact-type). ```mermaid @@ -203,23 +203,23 @@ sequenceDiagram Note over C,R: Save to OCI Layout or file system - C->>+C: Save manifest, config and blobs + C->>+C: Save manifest, config and blobs Note over C: Pull Workflow Ends ``` ## The Power of Associations The introduction of Reference Types (Associations) opens a world of possibilities in -managing and linking of OCI Artifacts while also empowering the following scenarios: +managing and linking of OCI Artifacts while also empowering the following scenarios: -- Discovery and distribution of artifacts like SBOMs or signatures for supply chain. -- Movement of a graph of OCI content across environments. -- Content management of a graph of artifacts by archiving, deleting or moving them +- Discovery and distribution of artifacts like SBOMs or signatures for supply chain. +- Movement of a graph of OCI content across environments. +- Content management of a graph of artifacts by archiving, deleting or moving them together. -To further explore this concept, dive deeper into the +To further explore this concept, dive deeper into the [OCI Distribution Specification][distribution-spec] and the [OCI Image Specification][image-spec]. -These comprehensive guides will provide more insights into the use of +These comprehensive guides will provide more insights into the use of reference types and other details of managing OCI Artifacts. [listing-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc3/spec.md#listing-referrers diff --git a/docs/glossary.mdx b/docs/glossary.mdx index a03bd225..e04847da 100644 --- a/docs/glossary.mdx +++ b/docs/glossary.mdx @@ -7,43 +7,43 @@ sidebar_position: 80 ### Annotations -[Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) are string key-value pairs similar to labels. -Annotations are supported by OCI Image Manifest and OCI Content Descriptors. +[Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) are string key-value pairs similar to labels. +Annotations are supported by OCI Image Manifest and OCI Content Descriptors. You can refer to our [how-to guide](./how_to_guides/manifest_annotations.mdx) to understand how ORAS CLI could be used to add them. ### Artifacts -Artifacts are a conceptual piece of content stored as [Blobs](#blob) with an accompanying Manifest containing a [Config](#config). -We can [push](./commands/oras_push.mdx), -[pull](./commands/oras_pull.mdx), -[attach](./commands/oras_attach.mdx) artifacts using the ORAS CLI. -In order to understand the usage better, +Artifacts are a conceptual piece of content stored as [Blobs](#blob) with an accompanying Manifest containing a [Config](#config). +We can [push](./commands/oras_push.mdx), +[pull](./commands/oras_pull.mdx), +[attach](./commands/oras_attach.mdx) artifacts using the ORAS CLI. +In order to understand the usage better, you may follow the steps in our [quick start guide](./quickstart.mdx). ### Blob -Blob (which stands for Binary Large Objects) is the content stored by a registry and is addressable by a Digest. -ORAS allows you to [fetch](./commands/oras_blob_fetch.mdx), -[delete](./commands/oras_blob_delete.mdx) +Blob (which stands for Binary Large Objects) is the content stored by a registry and is addressable by a Digest. +ORAS allows you to [fetch](./commands/oras_blob_fetch.mdx), +[delete](./commands/oras_blob_delete.mdx) and [push](./commands/oras_blob_push.mdx) blobs. ### Config -[Config](https://github.com/opencontainers/image-spec/blob/main/config.md) is the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem changesets. +[Config](https://github.com/opencontainers/image-spec/blob/main/config.md) is the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem changesets. You may use [`oras manifest fetch-config`](./commands/oras_manifest_fetch-config.mdx) to check out the config of your artifact. ### Container Images -A [container image](https://www.docker.com/resources/what-container/#:~:text=A%20Docker%20container%20image%20is,tools%2C%20system%20libraries%20and%20settings.) is a small, standalone, -executable file that contains all the components required to run an application, +A [container image](https://www.docker.com/resources/what-container/#:~:text=A%20Docker%20container%20image%20is,tools%2C%20system%20libraries%20and%20settings.) is a small, standalone, +executable file that contains all the components required to run an application, including the code, runtime, system tools, system libraries, and settings. ### Content Descriptors -A [Content Descriptor](https://github.com/opencontainers/image-spec/blob/main/descriptor.md) (or simply Descriptor) describes the disposition of the targeted content. -It includes the type of the content, -a content identifier (digest), -and the byte-size of the raw content. +A [Content Descriptor](https://github.com/opencontainers/image-spec/blob/main/descriptor.md) (or simply Descriptor) describes the disposition of the targeted content. +It includes the type of the content, +a content identifier (digest), +and the byte-size of the raw content. Optionally, it includes the type of artifact it is describing. ### Digest @@ -60,8 +60,8 @@ The Distribution Specification Project includes a process and API for prototypin ### Image Layout -The [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) is the directory structure for OCI content-addressable blobs and location-addressable references (refs). -It must contain a `blobs` directory, `oci-layout` file and an `index.json` file. +The [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md) is the directory structure for OCI content-addressable blobs and location-addressable references (refs). +It must contain a `blobs` directory, `oci-layout` file and an `index.json` file. To learn more, check out the [how-to guide](./how_to_guides/distributing_oci_layouts.mdx) on OCI Layouts. ### Image Manifests @@ -70,33 +70,33 @@ An [image manifest](https://github.com/opencontainers/image-spec/blob/main/manif ### Image-spec -The [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/main/spec.md) defines an OCI Image, -consisting of an image manifest, -an image index (optional), -a set of filesystem layers, +The [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/main/spec.md) defines an OCI Image, +consisting of an image manifest, +an image index (optional), +a set of filesystem layers, and a configuration. ### Image Index Specification -The [image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md) is a higher-level manifest which points to specific image manifests, ideal for one or more platforms. +The [image index](https://github.com/opencontainers/image-spec/blob/main/image-index.md) is a higher-level manifest which points to specific image manifests, ideal for one or more platforms. It is a multi-descriptor entry point. ### Local Registry -A registry is a place where container images and artifacts can easily be stored and accessed. -Whereas, a local registry (like [zot](https://zotregistry.dev/)) is a registry that is present on our local machine. +A registry is a place where container images and artifacts can easily be stored and accessed. +Whereas, a local registry (like [zot](https://zotregistry.dev/)) is a registry that is present on our local machine. You can follow our [quick start guide](./quickstart.mdx) if you would like to try using zot registry. ### Manifest Referrers API -Artifact-manifest provides the ability to reference artifacts to existing artifacts. Reference artifacts include signatures, -SBoMs and many other types. +Artifact-manifest provides the ability to reference artifacts to existing artifacts. Reference artifacts include signatures, +SBoMs and many other types. The [manifest `referrers` API](https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md) returns all artifacts that have a `subject` of the given manifest digest. ### Referrer API -The Referrers API returns a list of manifests that reference a blob. -You can understand how to use this API by referring to the [details](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers) given in the distribution spec. +The Referrers API returns a list of manifests that reference a blob. +You can understand how to use this API by referring to the [details](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers) given in the distribution spec. ### Referrer Tag Schema @@ -108,21 +108,21 @@ A registry is like a central repository where you can store, share and manage co ### Remote Registry -A remote registry is when our registry is remotely available such as Docker Hub, ghcr.io, etc. -We can use ORAS CLI to perform many operations such as [pushing](./commands/oras_push.mdx), -[pulling](./commands/oras_pull.mdx), +A remote registry is when our registry is remotely available such as Docker Hub, ghcr.io, etc. +We can use ORAS CLI to perform many operations such as [pushing](./commands/oras_push.mdx), +[pulling](./commands/oras_pull.mdx), [attaching](./commands/oras_attach.mdx) artifacts. ### Software Bill of Materials -A codebase's open source and third-party components are listed in a software Bill of Materials (SBOM). -Additionally, an SBOM provides the versions of the components used in the codebase, -their patch status, -and the licences that govern them. +A codebase's open source and third-party components are listed in a software Bill of Materials (SBOM). +Additionally, an SBOM provides the versions of the components used in the codebase, +their patch status, +and the licences that govern them. ### Supply Chain Security -Supply chain security emphasises risk management of outside vendors, suppliers, logistics, and transportation. +Supply chain security emphasises risk management of outside vendors, suppliers, logistics, and transportation. It recognises, assesses, and reduces risks related to collaborating with other organisations as a part of your supply chain. ### Tags diff --git a/docs/how_to_guides/authentication.mdx b/docs/how_to_guides/authentication.mdx index 8308557d..0dd7ac9f 100644 --- a/docs/how_to_guides/authentication.mdx +++ b/docs/how_to_guides/authentication.mdx @@ -9,7 +9,7 @@ There are two ways we will be covering in this guide to authenticate with OCI Re ### Method 1: Authentication Using the `config` File -This method is straightforward but insecure. It may be used for testing purposes. In this method, the command will store the credentials in `~/.docker/config.json` which is the same file used as the docker client. +This method is straightforward but insecure. It may be used for testing purposes. In this method, the command will store the credentials in `~/.docker/config.json` which is the same file used as the docker client. Please note that if you have previously used `docker login`, the credentials will get reused. @@ -36,7 +36,7 @@ An external helper program is needed to interact with a specific keychain or ext Prerequisites to follow through with these commands: 1. According to your operating system, you may download a credential helper from among these: - - [D-Bus Secret Service](https://github.com/docker/docker-credential-helpers/releases) + - [D-Bus Secret Service](https://github.com/docker/docker-credential-helpers/releases) - [Apple macOS keychain](https://github.com/docker/docker-credential-helpers/releases) - [Microsoft Windows Credential Manager](https://github.com/docker/docker-credential-helpers/releases) - [pass](https://www.passwordstore.org/) @@ -54,7 +54,7 @@ Configure the credential store in the `~/.docker/config.json` file. Your file sh } ``` -**Note**: Please replace pass with the credential helper you want to use. +**Note**: Please replace pass with the credential helper you want to use. **Step 2** diff --git a/docs/how_to_guides/distributing_oci_layouts.mdx b/docs/how_to_guides/distributing_oci_layouts.mdx index d63c148f..69761d8e 100644 --- a/docs/how_to_guides/distributing_oci_layouts.mdx +++ b/docs/how_to_guides/distributing_oci_layouts.mdx @@ -13,7 +13,7 @@ The directory structure for OCI content-addressable blobs and location-addressab - `index.json` file: The image index is a multi-descriptor entry point. -## Creating an OCI Image +## Creating an OCI Image ### Step 1: Writing in the Dockerfile @@ -80,7 +80,7 @@ In the following example, we are pushing the image to a local registry like zot: ``` oras cp --from-oci-layout ./hello-world.tar:v1 localhost:5000/hello-artifact:v1 -``` +``` Expected output: diff --git a/docs/how_to_guides/manifest_config.mdx b/docs/how_to_guides/manifest_config.mdx index 51d53608..f356b071 100644 --- a/docs/how_to_guides/manifest_config.mdx +++ b/docs/how_to_guides/manifest_config.mdx @@ -27,7 +27,7 @@ To push a file `hi.txt` with the custom manifest config file `config.json`, you oras push --config config.json localhost:5000/hello:latest hi.txt ``` -The media type of the config is set to the default value `application/vnd.unknown.config.v1+json`. +The media type of the config is set to the default value `application/vnd.unknown.config.v1+json`. Similar to the file reference, it is possible to change the media type of the manifest config. To push a file `hi.txt` with the custom manifest config file `config.json` with the custom media type `application/vnd.oras.config.v1+json`, run diff --git a/docs/how_to_guides/pushing_and_pulling.mdx b/docs/how_to_guides/pushing_and_pulling.mdx index 64b52837..54e54f7c 100644 --- a/docs/how_to_guides/pushing_and_pulling.mdx +++ b/docs/how_to_guides/pushing_and_pulling.mdx @@ -136,7 +136,7 @@ See [OCI Artifacts](https://github.com/opencontainers/image-spec/blob/main/manif } ``` -# Pulling +# Pulling Pulling artifacts involves specifying the content addressable artifact, along with the type of artifact. @@ -147,7 +147,7 @@ oras pull localhost:5000/hello-artifact:v2 ## Using cache when pulling artifacts ORAS pulls the artifact into a content-addressable storage (CAS) cache if the content is not available locally to save bandwidth and disk I/O. -Once the content is availabe in the cache, ORAS copies the artifact to the desired location. +Once the content is availabe in the cache, ORAS copies the artifact to the desired location. The cache directory is specified by using the environment variable `ORAS_CACHE`. If not specified, cache is not used. ``` diff --git a/docs/how_to_guides/verifying_binaries.mdx b/docs/how_to_guides/verifying_binaries.mdx index b52d0bd6..37411dae 100644 --- a/docs/how_to_guides/verifying_binaries.mdx +++ b/docs/how_to_guides/verifying_binaries.mdx @@ -5,12 +5,12 @@ sidebar_position: 10 # Validating ORAS CLI Binaries -After finding your [target release](https://github.com/oras-project/oras/releases), +After finding your [target release](https://github.com/oras-project/oras/releases), you may find the releaser's information under the `notes` section. The following commands can be used to verify the ORAS CLI binaries using GPG: -### Step 1: +### Step 1: First, we import the releaser's GPG Key which can be used for verification (here we have imported [Billy Zha](https://github.com/qweeah)'s key): @@ -20,7 +20,7 @@ $ curl -sSL https://github.com/qweeah.gpg | gpg --import - You can find the [GPG keys](https://github.com/oras-project/oras/blob/main/KEYS) which have been used for ORAS releases. -### Step 2: +### Step 2: You can run the following command to check if the key has been imported: @@ -31,7 +31,7 @@ pub rsa4096 2023-02-28 [SC] [expires: 2024-02-28] uid [ unknown] Billy Zha ``` -### Step 3: +### Step 3: Verify our binaries using the command: diff --git a/docs/installation.mdx b/docs/installation.mdx index 957c123a..67fe98c8 100644 --- a/docs/installation.mdx +++ b/docs/installation.mdx @@ -102,7 +102,7 @@ Nix is a tool that takes a unique approach to package management and system conf The Nix Packages collection ([Nixpkgs](https://github.com/NixOS/nixpkgs)) is a set of over 80 000 packages for the Nix package manager. oras also has a [Nix package](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/oras/default.nix) available in the Nixpkgs repository. - + :::info You can install nix CLI from [here](https://nixos.org/download.html). diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 9dc73bc9..355222f4 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -1,26 +1,26 @@ --- -title: Quick Start -sidebar_position: 14 +title: Quick Start +sidebar_position: 14 --- # Distributing OCI artifacts using ORAS -To distribute OCI artifacts, we need to understand OCI registries. -These registries store container images and other artifacts for easy access. -Distributing OCI artifacts means pushing them to these registries so others can pull them for use. +To distribute OCI artifacts, we need to understand OCI registries. +These registries store container images and other artifacts for easy access. +Distributing OCI artifacts means pushing them to these registries so others can pull them for use. -We will be using [zot registry](https://zotregistry.dev/) in this guide. +We will be using [zot registry](https://zotregistry.dev/) in this guide. Zot registry is an OCI-native container registry for distributing container images and OCI artifacts. In order to follow the steps given, you would be required to install the ORAS CLI. -You can follow the [installation guide](./installation.mdx) to do so. +You can follow the [installation guide](./installation.mdx) to do so. -## Install zot registry +## Install zot registry We will be running zot using docker. However, you can refer to their [installation guide](https://zotregistry.dev/install-guides/install-guide-linux/) to find more ways to install the registry. **Prerequisites** -- [Docker](https://www.docker.com/) +- [Docker](https://www.docker.com/) ``` docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/project-zot/zot-linux-amd64:latest @@ -28,7 +28,7 @@ docker run -d -p 5000:5000 --name oras-quickstart ghcr.io/project-zot/zot-linux- ## Distribution of OCI artifacts -Let's push an OCI artifact to the registry using the ORAS CLI. +Let's push an OCI artifact to the registry using the ORAS CLI. ### Step 1: Create a sample file @@ -72,7 +72,7 @@ Digest: sha256:19e1b5170646a1500a1ac56bad28675ab72dc49038e69ba56eb7556ec478859f ## Attach an artifact -First, let's create another sample file to attach to the previously uploaded artifact. +First, let's create another sample file to attach to the previously uploaded artifact. ### Step 1: Create a sample file @@ -94,7 +94,7 @@ Attached to [registry] localhost:5000/hello-artifact@sha256:327db68f73d0ed53d528 Digest: sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe217a09cee ``` -### Step 3: View referrers +### Step 3: View referrers ``` oras discover localhost:5000/hello-artifact:v1 @@ -112,7 +112,7 @@ doc/example sha256:bcdd6799fed0fca0eaedfc1c642f3d1dd7b8e78b43986a89935d6fe21 ## Clean up -Stop and remove the running quick start registry and the uploaded content. +Stop and remove the running quick start registry and the uploaded content. ``` docker rm $(docker stop oras-quickstart) @@ -120,6 +120,6 @@ docker rm $(docker stop oras-quickstart) ## Conclusion -You can now successfully push OCI artifacts to your zot registry! +You can now successfully push OCI artifacts to your zot registry! As OCI registries are used to securely store and share container images, they greatly help with collaboration and code sharing. They enable teams to acquire and use images and artifacts through a standardized artifact interface. This is why it is considered to play a crucial role in maintaining consistency among teams. \ No newline at end of file