From aa3f55efc087966ce2621c9b8b20975153a2d163 Mon Sep 17 00:00:00 2001
From: Deepesha Burse <deepeshaburse@Deepeshas-MacBook-Air.local>
Date: Mon, 17 Jul 2023 20:56:30 +0530
Subject: [PATCH] docs: add guide to distribute artifacts to oci image

Signed-off-by: Deepesha Burse <deepeshaburse@Deepeshas-MacBook-Air.local>
---
 docs/how_to_guides/pushing_to_oci_images.mdx | 115 +++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/how_to_guides/pushing_to_oci_images.mdx

diff --git a/docs/how_to_guides/pushing_to_oci_images.mdx b/docs/how_to_guides/pushing_to_oci_images.mdx
new file mode 100644
index 00000000..1a0698b5
--- /dev/null
+++ b/docs/how_to_guides/pushing_to_oci_images.mdx
@@ -0,0 +1,115 @@
+---
+title: Distribute Images and Artifacts in an OCI Image Layout
+sidebar_position: 6
+---
+
+# Distributing an artifact to OCI Image Layout
+
+### Phase 1: Creating an OCI Image 
+
+#### Step 1.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!'
+```
+
+FROM: This command initializes a new build stage and sets the Base Image for subsequent instructions.
+
+CMD: This command is used to specify what needs to be run after the image has been built.
+
+#### Step 1.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.
+
+Flags used:
+
+| file or -f   | Name of the Dockerfile (default: PATH/Dockerfile)    |
+|--------------|------------------------------------------------------|
+| output or -o | Output destination (format: type=local,dest=path)    |
+
+#### Step 1.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
+```
+
+### Phase 2: Push the OCI Image to a Repository
+
+You may use [`oras copy`](../commands/oras_copy.mdx) to push the OCI Image on your local disk to a repository.
+
+In the following example, we are pushing the image to a remote repository like docker,
+
+```
+oras cp --from-oci-layout ./hello-world.tar:v1 docker.io/deepeshaburse/deepesha-test:v1
+``` 
+
+Expected output:
+
+```
+Copied [oci-layout] ./hello-world.tar:v1 => [registry] docker.io/deepeshaburse/deepesha-test:v1
+Digest: sha256:3fd491e6dc3ce66cae989d23b3f3d5752314cd1793d0c580d3fd8bb280d07809
+```
+
+### Phase 3: Pull the OCI Image from a Repository
+
+You can simply pull the OCI image using the [`oras pull`](../commands/oras_pull.mdx) command.
+
+```
+oras pull docker.io/deepeshaburse/deepesha-test:v1
+```
+
+Expected Output:
+
+```
+Downloaded empty artifact
+Pulled [registry] docker.io/deepeshaburse/deepesha-test: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
+```
\ No newline at end of file