docs: adds build workflow to getting started guide

Closes emporous#9 Signed-off-by: Jennifer Power <[email protected]>
jpower432 · Jul 28, 2022 · 1b1d80c · 1b1d80c
1 parent 8276d24
commit 1b1d80c
Show file tree

Hide file tree

Showing 8 changed files with 322 additions and 72 deletions.
diff --git a/content/docs/quick-start/_index.adoc b/content/docs/quick-start/_index.adoc
@@ -101,26 +101,43 @@ uor-workspace
 1 directory, 3 files
 ----
 
-=== Publishing a Collection
+=== Building a Collection
 
-With the desired set of files contained within the `uor-workspace` directory, the next step is to publishing a collection. This process performs three actions:
+With the desired set of files contained within the `uor-workspace` directory, the next step is to build a collection. This process performs three actions:
 
 1. Discovers all content within the workspace
 2. Produces an OCI artifact based on the content of the collection
-3. Publishes the artifact to a remote repository.
+3. Store the artifact in a local build cache. 
+
+The location of the build cache can be set by exporting the environment variable `UOR_CACHE`. The default location is `~/.uor/cache`.
 
-To publish the collection to a remote registry, let's say that an instance of `registry:2` was running on our local machine and there is the desire to publish the collection to `localhost:5000/uor-framework/getting-started:latest`.
+To build and store the collection, let's say there is the desire to eventually publish the collection to `localhost:5000/uor-framework/getting-started:latest`.
 
-Using the `push` subcommand, execute the following to publish the workspace to a remote registry. Additional options are also available for specifying the location of a file containing authentication details or communicating with an insecure or HTTP based registry if necessary. 
+Using the `build` subcommand, execute the following to build and store the workspace:
 
 [source, shell]
 ----
-$ client push uor-workspace localhost:5000/uor-framework/getting-started:latest
+$ client build uor-workspace localhost:5000/uor-framework/getting-started:latest
 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8 
 WARN[0000] reference for unknown type: image/jpeg       
 WARN[0000] reference for unknown type: application/vnd.uor.config.v1+json 
+INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 built with reference name localhost:5000/uor-framework/getting-started:latest 
+----
+
+Do not be concerned about the `WARN` messages in the output of the _build_ execution. These are being emitted by the underlying link:https://oras.land[ORAS] library to client utilizes.
+
+=== Publishing a Collection
+
+To publish the collection to a remote registry, let's say that an instance of `registry:2` was running on our local machine and there is the desire to publish the stored collection to `localhost:5000/uor-framework/getting-started:latest`.
+
+Using the `push` subcommand, execute the following to publish the stored collection to a remote registry. Additional options are also available for specifying the location of a file containing authentication details or communicating with an insecure or HTTP based registry if necessary. 
+
+[source, shell]
+----
+$ client push localhost:5000/uor-framework/getting-started:latest
+
 INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 published to localhost:5000/uor-framework/getting-started:latest 
 ----
 
@@ -311,18 +328,27 @@ EOF
 
 Associating a `DataSetConfiguration` to a collection is achieved when pushing a workspace to a remote registry by specifying the `--dsconfig` flag and referencing the location of the resource.
 
-=== Publishing a Collection With Attributes
+=== Building a Collection With Attributes
 
-Publish a new tag of the collection called `dsconfig` with the additional metadata associated to the content by executing the following command:
+Store a new tag of the collection called `dsconfig` with the additional metadata associated to the content by executing the following command:
 
 [source, shell]
 ----
-$ client push --dsconfig=dataset-configuration.yaml uor-workspace localhost:5000/uor-framework/getting-started:dsconfig
+$ client build --dsconfig=dataset-configuration.yaml uor-workspace localhost:5000/uor-framework/getting-started:dsconfig
 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8 
 WARN[0000] reference for unknown type: image/jpeg       
 WARN[0000] reference for unknown type: application/vnd.uor.config.v1+json 
+INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 built with reference name localhost:5000/uor-framework/getting-started:latest 
+----
+
+Publish the collection to the remote registry.
+
+[source, shell]
+----
+$ client push localhost:5000/uor-framework/getting-started:dsconfig
+
 INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 published to localhost:5000/uor-framework/getting-started:latest 
 ----
 

diff --git a/docs/categories/quickstart/index.xml b/docs/categories/quickstart/index.xml
@@ -163,9 +163,9 @@ uor-workspace
 &lt;/div&gt;
 &lt;/div&gt;
 &lt;div class=&#34;sect2&#34;&gt;
-&lt;h3 id=&#34;_publishing_a_collection&#34;&gt;Publishing a Collection&lt;/h3&gt;
+&lt;h3 id=&#34;_building_a_collection&#34;&gt;Building a Collection&lt;/h3&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;With the desired set of files contained within the &lt;code&gt;uor-workspace&lt;/code&gt; directory, the next step is to publishing a collection. This process performs three actions:&lt;/p&gt;
+&lt;p&gt;With the desired set of files contained within the &lt;code&gt;uor-workspace&lt;/code&gt; directory, the next step is to build a collection. This process performs three actions:&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;olist arabic&#34;&gt;
 &lt;ol class=&#34;arabic&#34;&gt;
@@ -176,24 +176,46 @@ uor-workspace
 &lt;p&gt;Produces an OCI artifact based on the content of the collection&lt;/p&gt;
 &lt;/li&gt;
 &lt;li&gt;
-&lt;p&gt;Publishes the artifact to a remote repository.&lt;/p&gt;
+&lt;p&gt;Store the artifact in a local build cache.&lt;/p&gt;
 &lt;/li&gt;
 &lt;/ol&gt;
 &lt;/div&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;To publish the collection to a remote registry, let’s say that an instance of &lt;code&gt;registry:2&lt;/code&gt; was running on our local machine and there is the desire to publish the collection to &lt;code&gt;localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;.&lt;/p&gt;
+&lt;p&gt;The location of the build cache can be set by exporting the environment variable &lt;code&gt;UOR_CACHE&lt;/code&gt;. The default location is &lt;code&gt;~/.uor/cache&lt;/code&gt;.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;To build and store the collection, let’s say there is the desire to eventually publish the collection to &lt;code&gt;localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;.&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;Using the &lt;code&gt;push&lt;/code&gt; subcommand, execute the following to publish the workspace to a remote registry. Additional options are also available for specifying the location of a file containing authentication details or communicating with an insecure or HTTP based registry if necessary.&lt;/p&gt;
+&lt;p&gt;Using the &lt;code&gt;build&lt;/code&gt; subcommand, execute the following to build and store the workspace:&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;listingblock&#34;&gt;
 &lt;div class=&#34;content&#34;&gt;
-&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push uor-workspace localhost:5000/uor-framework/getting-started:latest
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client build uor-workspace localhost:5000/uor-framework/getting-started:latest
 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: image/jpeg
 WARN[0000] reference for unknown type: application/vnd.uor.config.v1+json
+INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 built with reference name localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;Do not be concerned about the &lt;code&gt;WARN&lt;/code&gt; messages in the output of the &lt;em&gt;build&lt;/em&gt; execution. These are being emitted by the underlying &lt;a href=&#34;https://oras.land&#34;&gt;ORAS&lt;/a&gt; library to client utilizes.&lt;/p&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect2&#34;&gt;
+&lt;h3 id=&#34;_publishing_a_collection&#34;&gt;Publishing a Collection&lt;/h3&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;To publish the collection to a remote registry, let’s say that an instance of &lt;code&gt;registry:2&lt;/code&gt; was running on our local machine and there is the desire to publish the stored collection to &lt;code&gt;localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;Using the &lt;code&gt;push&lt;/code&gt; subcommand, execute the following to publish the stored collection to a remote registry. Additional options are also available for specifying the location of a file containing authentication details or communicating with an insecure or HTTP based registry if necessary.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;content&#34;&gt;
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push localhost:5000/uor-framework/getting-started:latest
+
 INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 published to localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
 &lt;/div&gt;
 &lt;/div&gt;
@@ -427,18 +449,28 @@ EOF&lt;/code&gt;&lt;/pre&gt;
 &lt;p&gt;Associating a &lt;code&gt;DataSetConfiguration&lt;/code&gt; to a collection is achieved when pushing a workspace to a remote registry by specifying the &lt;code&gt;--dsconfig&lt;/code&gt; flag and referencing the location of the resource.&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;sect2&#34;&gt;
-&lt;h3 id=&#34;_publishing_a_collection_with_attributes&#34;&gt;Publishing a Collection With Attributes&lt;/h3&gt;
+&lt;h3 id=&#34;_building_a_collection_with_attributes&#34;&gt;Building a Collection With Attributes&lt;/h3&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;Publish a new tag of the collection called &lt;code&gt;dsconfig&lt;/code&gt; with the additional metadata associated to the content by executing the following command:&lt;/p&gt;
+&lt;p&gt;Store a new tag of the collection called &lt;code&gt;dsconfig&lt;/code&gt; with the additional metadata associated to the content by executing the following command:&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;listingblock&#34;&gt;
 &lt;div class=&#34;content&#34;&gt;
-&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push --dsconfig=dataset-configuration.yaml uor-workspace localhost:5000/uor-framework/getting-started:dsconfig
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client build --dsconfig=dataset-configuration.yaml uor-workspace localhost:5000/uor-framework/getting-started:dsconfig
 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: image/jpeg
 WARN[0000] reference for unknown type: application/vnd.uor.config.v1+json
+INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 built with reference name localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;Publish the collection to the remote registry.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;content&#34;&gt;
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push localhost:5000/uor-framework/getting-started:dsconfig
+
 INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 published to localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
 &lt;/div&gt;
 &lt;/div&gt;

diff --git a/docs/categories/uor/index.xml b/docs/categories/uor/index.xml
@@ -163,9 +163,9 @@ uor-workspace
 &lt;/div&gt;
 &lt;/div&gt;
 &lt;div class=&#34;sect2&#34;&gt;
-&lt;h3 id=&#34;_publishing_a_collection&#34;&gt;Publishing a Collection&lt;/h3&gt;
+&lt;h3 id=&#34;_building_a_collection&#34;&gt;Building a Collection&lt;/h3&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;With the desired set of files contained within the &lt;code&gt;uor-workspace&lt;/code&gt; directory, the next step is to publishing a collection. This process performs three actions:&lt;/p&gt;
+&lt;p&gt;With the desired set of files contained within the &lt;code&gt;uor-workspace&lt;/code&gt; directory, the next step is to build a collection. This process performs three actions:&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;olist arabic&#34;&gt;
 &lt;ol class=&#34;arabic&#34;&gt;
@@ -176,24 +176,46 @@ uor-workspace
 &lt;p&gt;Produces an OCI artifact based on the content of the collection&lt;/p&gt;
 &lt;/li&gt;
 &lt;li&gt;
-&lt;p&gt;Publishes the artifact to a remote repository.&lt;/p&gt;
+&lt;p&gt;Store the artifact in a local build cache.&lt;/p&gt;
 &lt;/li&gt;
 &lt;/ol&gt;
 &lt;/div&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;To publish the collection to a remote registry, let’s say that an instance of &lt;code&gt;registry:2&lt;/code&gt; was running on our local machine and there is the desire to publish the collection to &lt;code&gt;localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;.&lt;/p&gt;
+&lt;p&gt;The location of the build cache can be set by exporting the environment variable &lt;code&gt;UOR_CACHE&lt;/code&gt;. The default location is &lt;code&gt;~/.uor/cache&lt;/code&gt;.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;To build and store the collection, let’s say there is the desire to eventually publish the collection to &lt;code&gt;localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;.&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;Using the &lt;code&gt;push&lt;/code&gt; subcommand, execute the following to publish the workspace to a remote registry. Additional options are also available for specifying the location of a file containing authentication details or communicating with an insecure or HTTP based registry if necessary.&lt;/p&gt;
+&lt;p&gt;Using the &lt;code&gt;build&lt;/code&gt; subcommand, execute the following to build and store the workspace:&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;listingblock&#34;&gt;
 &lt;div class=&#34;content&#34;&gt;
-&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push uor-workspace localhost:5000/uor-framework/getting-started:latest
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client build uor-workspace localhost:5000/uor-framework/getting-started:latest
 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: image/jpeg
 WARN[0000] reference for unknown type: application/vnd.uor.config.v1+json
+INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 built with reference name localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;Do not be concerned about the &lt;code&gt;WARN&lt;/code&gt; messages in the output of the &lt;em&gt;build&lt;/em&gt; execution. These are being emitted by the underlying &lt;a href=&#34;https://oras.land&#34;&gt;ORAS&lt;/a&gt; library to client utilizes.&lt;/p&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;sect2&#34;&gt;
+&lt;h3 id=&#34;_publishing_a_collection&#34;&gt;Publishing a Collection&lt;/h3&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;To publish the collection to a remote registry, let’s say that an instance of &lt;code&gt;registry:2&lt;/code&gt; was running on our local machine and there is the desire to publish the stored collection to &lt;code&gt;localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;Using the &lt;code&gt;push&lt;/code&gt; subcommand, execute the following to publish the stored collection to a remote registry. Additional options are also available for specifying the location of a file containing authentication details or communicating with an insecure or HTTP based registry if necessary.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;content&#34;&gt;
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push localhost:5000/uor-framework/getting-started:latest
+
 INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 published to localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
 &lt;/div&gt;
 &lt;/div&gt;
@@ -427,18 +449,28 @@ EOF&lt;/code&gt;&lt;/pre&gt;
 &lt;p&gt;Associating a &lt;code&gt;DataSetConfiguration&lt;/code&gt; to a collection is achieved when pushing a workspace to a remote registry by specifying the &lt;code&gt;--dsconfig&lt;/code&gt; flag and referencing the location of the resource.&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;sect2&#34;&gt;
-&lt;h3 id=&#34;_publishing_a_collection_with_attributes&#34;&gt;Publishing a Collection With Attributes&lt;/h3&gt;
+&lt;h3 id=&#34;_building_a_collection_with_attributes&#34;&gt;Building a Collection With Attributes&lt;/h3&gt;
 &lt;div class=&#34;paragraph&#34;&gt;
-&lt;p&gt;Publish a new tag of the collection called &lt;code&gt;dsconfig&lt;/code&gt; with the additional metadata associated to the content by executing the following command:&lt;/p&gt;
+&lt;p&gt;Store a new tag of the collection called &lt;code&gt;dsconfig&lt;/code&gt; with the additional metadata associated to the content by executing the following command:&lt;/p&gt;
 &lt;/div&gt;
 &lt;div class=&#34;listingblock&#34;&gt;
 &lt;div class=&#34;content&#34;&gt;
-&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push --dsconfig=dataset-configuration.yaml uor-workspace localhost:5000/uor-framework/getting-started:dsconfig
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client build --dsconfig=dataset-configuration.yaml uor-workspace localhost:5000/uor-framework/getting-started:dsconfig
 
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: text/plain; charset=utf-8
 WARN[0000] reference for unknown type: image/jpeg
 WARN[0000] reference for unknown type: application/vnd.uor.config.v1+json
+INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 built with reference name localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
+&lt;/div&gt;
+&lt;/div&gt;
+&lt;div class=&#34;paragraph&#34;&gt;
+&lt;p&gt;Publish the collection to the remote registry.&lt;/p&gt;
+&lt;/div&gt;
+&lt;div class=&#34;listingblock&#34;&gt;
+&lt;div class=&#34;content&#34;&gt;
+&lt;pre class=&#34;highlight&#34;&gt;&lt;code class=&#34;language-shell&#34; data-lang=&#34;shell&#34;&gt;$ client push localhost:5000/uor-framework/getting-started:dsconfig
+
 INFO[0000] Artifact sha256:43c520531d3c1f2dbebb82aaa1e55d19040075772bcdf44db32561eea73c76e9 published to localhost:5000/uor-framework/getting-started:latest&lt;/code&gt;&lt;/pre&gt;
 &lt;/div&gt;
 &lt;/div&gt;