Add in-cluster offline devfile registry installation manual instruction

docs/modules/user-guide/pages/installation-incluster-registry-offline.adoc

@@ -0,0 +1,18 @@
+:description: Installation of In-Cluster Offline Devfile Registry
+:navtitle: Offline Devfile Registry
+:keywords: devfile, registry, stacks
+
+= Installation of In-Cluster Offline Devfile Registry
+
+A devfile refers to various resources, for example container images and starter projects. The current devfile registry currently does not store those supporting resources as part of the registry. This means that a user will need to have access to those resources when using those devfiles.
+
+To support the air gap installation of the devfile registry, the air gap scenario divides into 2 stages:
+
+. Build a devfile registry based on one or more source repositories, e.g. link:https://github.com/devfile/registry[devfile/registry], to build and package up a devfile registry that contains all the resources available for offline installation.
+. Install the devfile registry to a cluster to make it available for users to access the registry.
+
+include::partial$proc_stage-1-build-and-package-a-devfile-registry.adoc[]
+
+include::partial$proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc[]
+
+include::partial$proc_update-strategy-for-refreshing-registry-contents.adoc[]

docs/modules/user-guide/partials/assembly_devfile-registry.adoc

@@ -17,9 +17,10 @@ Get started with devfile registries:
 
 * xref:understanding-a-devfile-registry.adoc[]
 * xref:building-a-custom-devfile-registry.adoc[]
+* xref:installation-incluster-registry-offline.adoc[]
 * xref:deploying-a-devfile-registry.adoc[]
 * xref:adding-a-registry-schema.adoc[]
 * xref:creating-a-devfile-stack.adoc[]
 * xref:adding-a-stack-yaml-file.adoc[]
 
-For more information on the devfile registry, see the link:https://github.com/devfile/registry-support/blob/main/index/server/registry-REST-API.adoc[Registry REST API].
+For more information about the devfile registry, see the link:https://github.com/devfile/registry-support/blob/main/index/server/registry-REST-API.adoc[Registry REST API].

docs/modules/user-guide/partials/proc_stage-1-build-and-package-a-devfile-registry.adoc

@@ -0,0 +1,180 @@
+[id="stage-1-build-and-package-a-devfile-registry_{context}"]
+== Stage 1: Build and Package a Devfile Registry
+
+The main goal of this stage is:
+
+. Pull in resources into the registry as part of the registry build.
+. Modify the devfile to update references to those offline resources as part of the registry build.
+
+As part of the offline devfile registry build, we need to do a few steps.
+
+.Prerequisites
+
+* Golang 1.17.x or higher
+* Docker 17.05 or higher / Podman 4.0.x or higher
+* Git
+* Curl
+* Unzip
+
+=== Create Offline Registry
+
+Download / clone the link:https://github.com/devfile/registry[devfile/registry] repository.
+
+.Procedure: `git clone`
+
+* HTTP clone
++
+[source,bash]
+----
+git clone https://github.com/devfile/registry.git /path/to/registry
+----
++
+* SSH clone
++
+[source,bash]
+----
+git clone [email protected]:devfile/registry.git /path/to/registry
+----
+
+.Procedure: Download zip
+
+. Download link:https://github.com/devfile/registry[devfile/registry]
++
+[source,bash]
+----
+curl -L https://github.com/devfile/registry/archive/refs/heads/main.zip \
+  -o registry.zip
+----
++
+. Unzip registry
++
+[source,bash]
+----
+unzip registry.zip -d /path/to/registry
+----
+
+.Additional resources
+
+* Creating your own registry Git repository, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry]
+
+=== Packaging Starter Projects
+
+To package starter projects you will need to download them manually then place them under `/stacks/<stack>/<zip>-offline.zip`.
+
+*Note*: Starter projects must be packaged under a zip archive with the suffix `-offline` to be pulled into the registry.
+
+.Procedure
+
+. Zip - Download zip
++
+[source,bash]
+----
+curl -L <remote-url> -o <registry_root>/stacks/<stack>/<project>-offline.zip
+----
++
+Example
++
+[source,bash]
+----
+cd /path/to/registry
+curl -L https://code.quarkus.io/d?e=io.quarkus%3Aquarkus-resteasy&e=io.quarkus%3Aquarkus-micrometer&e=io.quarkus%3Aquarkus-smallrye-health&e=io.quarkus%3Aquarkus-openshift&cn=devfile \
+  -o stacks/java-quarkus/community-offline.zip
+----
++
+. Git - Package cloned contents into a zip
++
+[source,bash]
+----
+git clone <remote-url> <registry_root>/stacks/<stack>/<project>-offline.zip
+----
++
+Example
++
+[source,bash]
+----
+cd /path/to/registry
+git clone https://github.com/odo-devfiles/nodejs-ex.git \
+  stacks/nodejs/nodejs-starter-offline.zip
+----
++
+. GitHub - Download repository as a zip archive
++
+[source,bash]
+----
+curl -L https://github.com/<user|org>/<stack_repo_name>/archive/refs/heads/<main_branch>.zip \
+  -o <registry_root>/stacks/<stack>/<project>-offline.zip
+----
++
+Example
++
+[source,bash]
+----
+cd /path/to/registry
+curl -L https://github.com/odo-devfiles/nodejs-ex/archive/refs/heads/master.zip \
+  -o stacks/java-quarkus/nodejs-starter-offline.zip
+----
+
+=== Modify Devfile
+
+Modification is to the devfile will be needed to update references to those offline resources as part of the registry build. For all the items pulled into the registry, update the corresponding devfile entries to reference the resources within the offline version in the registry.
+
+.Procedure
+
+. Under `starterProjects`, find the starter project definition you want to make offline
+. Under the definition for the starter project find either `git` or `zip`, as seen here:
++
+.Starter Project Before
+====
+----
+...
+starterProjects:
+  - name: nodejs-starter
+    git:
+      remotes:
+        origin: https://github.com/odo-devfiles/nodejs-ex.git
+...
+----
+====
++
+. Do one of the following depending on the block type:
+  * If `git`, replace all of the `git` block with a `zip` block and add the `location` to be the path to the local file under the stack root directory (`<registry_root>/stacks/<stack>/`). 
+  * If `zip`, just replace the value of `location` to the same as mention for `git`. 
+. In either case, you should end up with something like as seen here:
++
+.Starter Project After
+====
+----
+...
+starterProjects:
+  - name: nodejs-starter
+    zip:
+      location: nodejs-starter-offline.zip
+...
+----
+====
+
+.Additional resources
+
+* More about starter projects in devfiles, see xref:adding-projects-to-a-devfile.adoc[Adding projects to a devfile]
+
+=== Build Registry
+
+.Procedure
+
+. Change to registry root (if not already there)
++
+[source,bash]
+----
+cd /path/to/registry
+----
++
+. Build Registry Image
++
+[source,bash]
+----
+bash .ci/build.sh
+----
+
+.Additional resources
+
+* For more information about building your own registry image, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry]

docs/modules/user-guide/partials/proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc

@@ -0,0 +1,35 @@
+[id="stage-2-install-a-devfile-registry-to-a-cluster_{context}"]
+== Stage 2: Install a Devfile Registry to a cluster
+
+The main goal of this stage (on top of the existing devfile registry install mechanism) is to install the images to the image registry.
+
+.Prerequisites
+
+* Docker 17.05 or higher / Podman 4.0.x or higher
+* OpenShift Container Platform 4.6 or higher
+
+=== Install Image into Cluster Image Registry
+
+The process of installing the built images into an offline image registry will depend on which image registry has deployed / has access to.
+
+.Procedure
+
+. OpenShift Image Registry
++
+Retag image using the form `<registry_ip>:<port>/<project>/<image>`. This can be done using `docker tag` or `podman tag`:
++
+[source,bash]
+----
+podman tag localhost/devfile-index <registry_ip>:<port>/<project>/devfile-index
+----
++
+Now you can push the retagged image to the OpenShift Image Registry at `<registry_ip>:<port>` by using `docker push` or `podman push`:
++
+[source,bash]
+----
+podman push <registry_ip>:<port>/<project>/devfile-index
+----
+
+.Additional resources
+
+* For more on interacting with the OpenShift Image Registry, see link:https://docs.openshift.com/container-platform/4.10/registry/accessing-the-registry.html[Accessing the registry]

docs/modules/user-guide/partials/proc_update-strategy-for-refreshing-registry-contents.adoc

@@ -0,0 +1,7 @@
+[id="update-strategy-for-refreshing-registry-contents_{context}"]
+== Update strategy for refreshing registry contents
+
+Steps to update an already deployed registry in the air gap scenario:
+
+. Rerun the registry build script to rebuild the devfile registry and package up the devfile registry that contains all the resources available for offline installation.
+. Update the existing devfile registry deployment with the new devfile registry to make it available for users to access the registry.