docs: add guide to distribute artifacts to oci image

docs/how_to_guides/distributing_oci_layouts.mdx

@@ -0,0 +1,120 @@
+---
+title: Distributing OCI Layouts
+sidebar_position: 6
+---
+
+# Distributing OCI Layouts
+
+The directory structure for OCI content-addressable blobs and location-addressable references (refs) is called the [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/main/image-layout.md). An OCI Image needs to include:
+
+- `blobs` directory: Each hash algorithm's directory and its children, which make up the object names in the blobs subdirectories, will hold the real content.
+
+- `oci-layout` file: This JSON object indicates the base of an Open Container Image Layout and provides information about the current image-layout version.
+
+- `index.json` file: The image index is a multi-descriptor entry point.
+
+## Creating an OCI Image 
+
+### Step 1: Writing in the Dockerfile
+
+Put the following commands in the `Dockerfile` in order to run an image of Alpine Linux.
+
+```
+FROM alpine
+CMD echo 'hello world!'
+```
+
+Our image is based on alpine and runs the command `echo hello world!`.
+
+### Step 2: Building the image using docker
+
+```
+docker buildx create —use
+```
+
+This command is used to create a new instance of a builder with a single node based on the current configuration.
+
+
+```
+docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1
+```
+
+Expected output:
+```
+[+] Building 7.0s (7/7) FINISHED                 docker-container:hungry_wilson
+ => [internal] booting buildkit                                            3.0s
+ => => pulling image moby/buildkit:buildx-stable-1                         2.5s
+ => => creating container buildx_buildkit_hungry_wilson0                   0.5s
+
+<!—truncate—>
+
+ => => exporting manifest sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd17  0.0s
+ => => exporting config sha256:5e9872dc690060c52e4ea6e9357aaebb9d9187b44a  0.0s
+ => => sending tarball                                                     0.0s
+```
+
+This command has multiple parts to break down:
+
+`build` is needed to build the OCI Image based on the Dockerfile we provide.
+hello-world:v1 is the name and tag associated with the image built.
+
+| Flag         | Description                                          |
+|--------------|------------------------------------------------------|
+| file or -f   | Name of the Dockerfile (default: PATH/Dockerfile)    |
+| output or -o | Output destination (format: type=local,dest=path)    |
+
+### Step 3: View the OCI Image
+
+If you would like to view the image, you will need to extract the `.tar` file first.
+
+```
+mkdir hello-world
+tar -xf ./hello-world.tar -C hello-world
+```
+
+## Push the OCI Image to a Repository
+
+You may use [`oras copy`](../commands/oras_copy.mdx) to push the OCI Image from your local disk to a repository.
+
+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:
+
+```
+Copied [oci-layout] ./hello-world.tar:v1 => [registry] localhost:5000/hello-artifact:v1
+Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809
+```
+
+## Pull the OCI Image from a Repository
+
+You can pull the OCI image using the [`oras pull`](../commands/oras_pull.mdx) command.
+
+```
+oras pull localhost:5000/hello-artifact:v1
+```
+
+Expected Output:
+
+```
+Downloaded empty artifact
+Pulled [registry] localhost:5000/hello-artifact:v1
+Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809
+```
+
+If you would like to access the artifact files from the OCI layout archive, you may run:
+
+```
+oras pull --oci-layout hello-world.tar:v1
+```
+
+Expected Output:
+
+```
+Downloaded empty artifact
+Pulled [oci-layout] hello-world.tar:v1
+Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809
+```