Enhance documentation
Change-Id: I4e5cff50e32f7fd47c7d6533f14502147d1001f3
Signed-off-by: wrider <lji@research.att.com>
diff --git a/docs/images/kong-extservice.png b/docs/images/kong-extservice.png
new file mode 100644
index 0000000..9fd7b0b
--- /dev/null
+++ b/docs/images/kong-extservice.png
Binary files differ
diff --git a/docs/images/nrtric-amber.png b/docs/images/nrtric-amber.png
new file mode 100644
index 0000000..66eb1de
--- /dev/null
+++ b/docs/images/nrtric-amber.png
Binary files differ
diff --git a/docs/index.rst b/docs/index.rst
index c1fed9b..d9f72e3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,9 +25,8 @@
:maxdepth: 2
:caption: Contents:
+ overview
release-notes
installation-guides
- user-guides
api-docs
developer-guides
-
diff --git a/docs/installation-aux.rst b/docs/installation-aux.rst
new file mode 100644
index 0000000..30cc8a2
--- /dev/null
+++ b/docs/installation-aux.rst
@@ -0,0 +1,96 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+Installing Near Realtime RIC in RIC Cluster
+===========================================
+
+Getting and Preparing Deployment Scripts
+----------------------------------------
+
+Run the following commands in a root shell:
+
+.. code:: bash
+
+ git clone http://gerrit.o-ran-sc.org/r/it/dep
+ cd RECIPE_EXAMPLE
+
+Edit the recipe files RIC_INFRA_RECIPE_EXAMPLE and RIC_PLATFORM_RECIPE_EXAMPLE. In particular the following values often need adaptation to local deployments:
+
+1. Docker registry URL;
+2. Docker registry credential;
+3. Helm repo credential;
+4. Component docker container image tags.
+
+
+Deploying the Infrastructure and Platform Groups
+------------------------------------------------
+
+After the recipes are edited, the Near Realtime RIIC is ready to be deployed.
+
+.. code:: bash
+
+ cd dep/bin
+ ./deploy-ric-infra ../RECIPE_EXAMPLE/RIC_INFRA_RECIPE_EXAMPLE
+ ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
+
+
+Checking the Deployment Status
+------------------------------
+
+Now check the deployment status and results similar to the below indicate a complete and successful deployment.
+
+.. code::
+
+ # helm list
+ NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
+ r1-a1mediator 1 Tue Nov 26 00:47:12 2019 DEPLOYED a1mediator-1.0.0 1.0 ricplt
+ r1-appmgr 1 Tue Nov 26 00:47:09 2019 DEPLOYED appmgr-1.1.0 1.0 ricplt
+ r1-dbaas1 1 Tue Nov 26 00:47:10 2019 DEPLOYED dbaas1-1.1.0 1.0 ricplt
+ r1-chartmuseum 1 Tue Nov 26 03:16:42 2019 DEPLOYED chartmuseum-0.0.1 0.1 ricinfra
+ r1-e2mgr 1 Tue Nov 26 00:47:10 2019 DEPLOYED e2mgr-1.1.0 1.0 ricplt
+ r1-e2term 1 Tue Nov 26 00:47:11 2019 DEPLOYED e2term-1.1.0 1.0 ricplt
+ r1-extsvcplt 1 Tue Nov 26 00:47:17 2019 DEPLOYED extsvcplt-0.2.0 1.0 ricplt
+ r1-jaegeradapter 1 Tue Nov 26 00:47:16 2019 DEPLOYED jaegeradapter-0.1.0 1.0 ricplt
+ r1-kong 1 Tue Nov 26 00:45:36 2019 DEPLOYED kong-1.0.0 1.0 ricinfra
+ r1-ricaux-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricaux
+ r1-ricinfra-credential 1 Tue Nov 26 00:45:43 2019 DEPLOYED credential-1.1.0 1.0 ricinfra
+ r1-ricplt-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricplt
+ r1-ricxapp-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricxapp
+ r1-rsm 1 Tue Nov 26 00:47:15 2019 DEPLOYED rsm-2.0.6 1.0 ricplt
+ r1-rtmgr 1 Tue Nov 26 00:47:09 2019 DEPLOYED rtmgr-1.1.0 1.0 ricplt
+ r1-submgr 1 Tue Nov 26 00:47:13 2019 DEPLOYED submgr-1.1.0 1.0 ricplt
+ r1-vespamgr 1 Tue Nov 26 00:47:14 2019 DEPLOYED vespamgr-0.0.1 1.0 ricplt
+ r1-xapp-tiller 1 Tue Nov 26 00:45:44 2019 DEPLOYED xapp-tiller-0.1.0 1.0 ricinfra
+ # kubectl get pods -n ricplt
+ NAME READY STATUS RESTARTS AGE
+ deployment-ricplt-a1mediator-5c4df477f9-6zxxx 1/1 Running 0 132m
+ deployment-ricplt-appmgr-65bc8b958c-tggg7 1/1 Running 0 132m
+ deployment-ricplt-dbaas-74bf584449-k484v 1/1 Running 0 132m
+ deployment-ricplt-e2mgr-74cd9865bc-hpn6b 1/1 Running 0 132m
+ deployment-ricplt-e2term-cc7b5d99-pkctr 1/1 Running 0 132m
+ deployment-ricplt-jaegeradapter-cc49c64dc-vj622 1/1 Running 0 131m
+ deployment-ricplt-rsm-599cd4d6c8-4jhft 1/1 Running 0 131m
+ deployment-ricplt-rtmgr-85d89868d6-58wvl 1/1 Running 1 132m
+ deployment-ricplt-submgr-7cbd697c7f-p9x4x 1/1 Running 0 132m
+ deployment-ricplt-vespamgr-7bb4c7585f-9z6qm 1/1 Running 0 132m
+ # kubectl get pods -n ricinfra
+ NAME READY STATUS RESTARTS AGE
+ deployment-ricinfra-chartmuseum-7d97f4b995-gkxsq 1/1 Running 0 133m
+ deployment-tiller-ricxapp-65f9cbc8d7-qcr5t 1/1 Running 0 133m
+ r1-kong-kong-84695ff65d-9sjwg 2/2 Running 2 133m
+ tiller-secret-generator-w6bnd 0/1 Completed 0 133m
+
diff --git a/docs/installation-guides.rst b/docs/installation-guides.rst
index 05231f5..cfd0b1f 100644
--- a/docs/installation-guides.rst
+++ b/docs/installation-guides.rst
@@ -19,109 +19,94 @@
:depth: 3
:local:
-========
-Abstract
-========
+===================
+Installation Guides
+===================
-This document describes how to install <Component>, it's dependencies and required system resources.
+This document describes how to install the components deployed by scripts and Helm charts
+under the it/dep repository, it's dependencies and required system resources.
.. contents::
:depth: 3
:local:
Version history
----------------------
+===============
+--------------------+--------------------+--------------------+--------------------+
| **Date** | **Ver.** | **Author** | **Comment** |
| | | | |
+--------------------+--------------------+--------------------+--------------------+
-| 20XX-XX-XX | 0.1.0 | | First draft |
-| | | | |
-+--------------------+--------------------+--------------------+--------------------+
-| | 0.1.1 | | |
-| | | | |
-+--------------------+--------------------+--------------------+--------------------+
-| | 1.0 | | |
-| | | | |
+| 2019-11-25 | 0.1.0 |Lusheng Ji | First draft |
| | | | |
+--------------------+--------------------+--------------------+--------------------+
-Introduction
-============
-.. <INTRODUCTION TO THE SCOPE AND INTENTION OF THIS DOCUMENT AS WELL AS TO THE SYSTEM TO BE INSTALLED>
+Overview
+========
-.<EXAMPLE>:
+The installation of Amber Near Realtime RAN Intelligent Controller is spread onto two separate
+Kubernetes clusters. The first cluster is used for deploying the Near Realtime RIC (platform and
+applications), and the other is for deploying other auxiliary functions. They are referred to as
+RIC cluster and AUX cluster respectively.
-This document describes the supported software and hardware configurations for the reference component as well as providing guidelines on how to install and configure such reference system.
+The following diagram depicts the installation architecture.
-The audience of this document is assumed to have good knowledge in RAN network nd Linux system.
+.. image:: images/nrtric-amber.png
+ :width: 600
+
+Within the RIC cluster, Kubernetes resources are deployed using three name spaces: ricinfra, ricplt, and ricxapp. Similarly, within the AUX cluster, Kubernetes resources are deployed using two name spaces: ricinfra, and ricaux.
+
+For each cluster, there is a Kong ingress controller that proxies incoming API calls into the cluster.
+With Kong, service APIs provided by Kubernetes resources can be accessed at the cluster node IP and
+port via a URL path. For cross-cluster communication, in addition to Kong, each Kubernetes namespace
+has a special Kubernetes service defined with endpoint pointing to the other cluster's Kong. This
+way any pod can access services exposed at the other cluster via the internal service hostname and port of
+this special service. The figure below illustrates the details of how Kong and external services work
+together to realize cross-cluster communication.
+
+.. image:: images/kong-extservice.png
+ :width: 600
-Preface
-=======
-.. <DESCRIBE NEEDED PREREQUISITES, PLANNING, ETC.>
+VirtualBox VMs as Installation Hosts
+=======================================
-<EXAMPLE>:
+The deployment of Amber Near Realtime RIC can be done on a wide range of hosts, including
+bare metal servers, OpenStack VMs, and VirtualBox VMs. This section provides detailed instructions
+for setting up Oracle VirtualBox VMs to be used as installation hosts.
-Before starting the installation of <project name>, some planning must preceed.
-
-.. note:any preperation you need before setting up sotfware and hardware
-
-
-Hardware requirements
-=====================
-.. <PROVIDE A LIST OF MINIMUM HARDWARE REQUIREMENTS NEEDED FOR THE INSTALL>
-
-<EXAMPLE>:
-
-Following minimum hardware requirements must be met for installation of <project name>:
-
-+--------------------+----------------------------------------------------+
-| **HW Aspect** | **Requirement** |
-| | |
-+--------------------+----------------------------------------------------+
-| **# of servers** | |
-+--------------------+----------------------------------------------------+
-| **CPU** | |
-| | |
-+--------------------+----------------------------------------------------+
-| **RAM** | |
-| | |
-+--------------------+----------------------------------------------------+
-| **Disk** | |
-| | |
-+--------------------+----------------------------------------------------+
-| **NICs** | |
-| | |
-| | |
-| | |
-| | |
-| | |
-+--------------------+----------------------------------------------------+
+.. include:: ./installation-virtualbox.rst
+One-Node Kubernetes Cluster
+============================
+
+This sectioin descriibes how to set up a one-node Kubernetes cluster onto a VM installation host.
+
+.. include:: ./installation-k8s1node.rst
-Software installation and deployment
-==========================================
-.. <DESCRIBE THE FULL PROCEDURES FOR THE INSTALLATION OF THE O-RAN COMPONENT INSTALLATION AND DEPLOYMENT>
+Installing Near Realtime RIC in RIC Cluster
+===========================================
-<EXAMPLE>:
+After the Kubernetes cluster is installed, teh next step is to install the (Near Realtime) RIC Platform.
-This section describes the installation of the <project name> installation on the reference hardware.
+.. include:: ./installation-ric.rst
+Installing Auxiliary Functions in AUX Cluster
+=============================================
-References
-==========
-.. <PROVIDE NEEDED/USEFUL REFERENCES>
+.. include:: ./installation-aux.rst
-<EXAMPLES>:
-OpenStack
-^^^^^^^^^^^
+Installing RIC Applications
+===========================================
+
+.. include:: ./installation-xapps.rst
+
+
diff --git a/docs/installation-k8s1node.rst b/docs/installation-k8s1node.rst
new file mode 100644
index 0000000..c4ec471
--- /dev/null
+++ b/docs/installation-k8s1node.rst
@@ -0,0 +1,80 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+
+
+Resource Requirements
+---------------------
+
+To run Near Realtime RAN Controller in a dev testing setting , the minimum requirement for resources is a VM with 4 vCPUs, 16G RAM, and at least 40G of vDisk space.
+
+
+
+Script for Setting Up 1-node Kubernetes Cluster
+-----------------------------------------------
+
+
+The it/dep repo can be used for generating a simple script that can help setting up a one-node Kubernetes cluster for dev and testing purposes. Related files are under the **ric-infra/00-Kubernetes** directory.
+
+Configurations
+--------------
+
+The generation of the script reads in the parameters from the following files:
+
+- etc/env.rc: Normally no change needed for this file. If where the Kubernetes cluster runs has special requirements, such as running private Docker registry with self-signed certificates, or hostnames that can be only resolved via private /etc/hosts entries, such parameters are entered into this file.
+- etc/infra.rc: This file specifies the versions docker host, Kubernetes, and Kubernetes CNI versions. If a version is left empty, the installation will use the default version that the OS package management software would install.
+- etc/openstack.rc: If the Kubernetes cluster is deployed on Open Stack VMs, this file specifies parameters for accessing the APIs of the Open Stack installation. This is not supported in Amber release yet.
+
+
+Generating Set-up Script
+------------------------
+
+After the configurations are updated, the following steps will create a script file that can be used for setting up a one-node Kubernetes cluster.
+
+::
+
+ cd bin
+ ./gen-cloud-init.sh
+
+A file named **k8s-1node-cloud-init.sh** would now appear under the bin directory.
+
+
+Setting up Kubernetes Cluster
+-----------------------------
+
+The new **k8s-1node-cloud-init.sh** file is now ready for setting up the Kubernetes cluster.
+
+It can be run from a root shell of an existing Ubuntu 16.04 or 18.04 VM. Running this script will replace any existing installation of Docker host, Kubernetes, and Helm on the VM.
+
+It can also be used as the user-data (a.k.a. cloud-init script) supplicated to Open Stack when launching a new Ubuntu 16.04 or 18.04 VM.
+
+Upon successful execution of the script, when integrated by the kubectl command, the VM should display information similar to below:
+
+::
+
+ # kubectl get pods --all-namespaces
+ NAMESPACE NAME READY STATUS RESTARTS AGE
+ kube-system coredns-5644d7b6d9-4gjp5 1/1 Running 0 103m
+ kube-system coredns-5644d7b6d9-pvsj8 1/1 Running 0 103m
+ kube-system etcd-ljitest 1/1 Running 0 102m
+ kube-system kube-apiserver-ljitest 1/1 Running 0 103m
+ kube-system kube-controller-manager-ljitest 1/1 Running 0 102m
+ kube-system kube-flannel-ds-amd64-nvjmq 1/1 Running 0 103m
+ kube-system kube-proxy-867v5 1/1 Running 0 103m
+ kube-system kube-scheduler-ljitest 1/1 Running 0 102m
+ kube-system tiller-deploy-68bf6dff8f-6pwvc 1/1 Running 0 102m
+
diff --git a/docs/installation-ric.rst b/docs/installation-ric.rst
new file mode 100644
index 0000000..26d0063
--- /dev/null
+++ b/docs/installation-ric.rst
@@ -0,0 +1,94 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+
+Getting and Preparing Deployment Scripts
+----------------------------------------
+
+Run the following commands in a root shell:
+
+.. code:: bash
+
+ git clone http://gerrit.o-ran-sc.org/r/it/dep
+ cd RECIPE_EXAMPLE
+
+Edit the recipe files RIC_INFRA_RECIPE_EXAMPLE and RIC_PLATFORM_RECIPE_EXAMPLE. In particular the following values often need adaptation to local deployments:
+
+1. Docker registry URL;
+2. Docker registry credential;
+3. Helm repo credential;
+4. Component docker container image tags.
+
+
+Deploying the Infrastructure and Platform Groups
+------------------------------------------------
+
+After the recipes are edited, the Near Realtime RIIC is ready to be deployed.
+
+.. code:: bash
+
+ cd dep/bin
+ ./deploy-ric-infra ../RECIPE_EXAMPLE/RIC_INFRA_RECIPE_EXAMPLE
+ ./deploy-ric-platform ../RECIPE_EXAMPLE/RIC_PLATFORM_RECIPE_EXAMPLE
+
+
+Checking the Deployment Status
+------------------------------
+
+Now check the deployment status and results similar to the below indicate a complete and successful deployment.
+
+.. code::
+
+ # helm list
+ NAME REVISION UPDATED STATUS CHART APP VERSION NAMESPACE
+ r1-a1mediator 1 Tue Nov 26 00:47:12 2019 DEPLOYED a1mediator-1.0.0 1.0 ricplt
+ r1-appmgr 1 Tue Nov 26 00:47:09 2019 DEPLOYED appmgr-1.1.0 1.0 ricplt
+ r1-dbaas1 1 Tue Nov 26 00:47:10 2019 DEPLOYED dbaas1-1.1.0 1.0 ricplt
+ r1-chartmuseum 1 Tue Nov 26 03:16:42 2019 DEPLOYED chartmuseum-0.0.1 0.1 ricinfra
+ r1-e2mgr 1 Tue Nov 26 00:47:10 2019 DEPLOYED e2mgr-1.1.0 1.0 ricplt
+ r1-e2term 1 Tue Nov 26 00:47:11 2019 DEPLOYED e2term-1.1.0 1.0 ricplt
+ r1-extsvcplt 1 Tue Nov 26 00:47:17 2019 DEPLOYED extsvcplt-0.2.0 1.0 ricplt
+ r1-jaegeradapter 1 Tue Nov 26 00:47:16 2019 DEPLOYED jaegeradapter-0.1.0 1.0 ricplt
+ r1-kong 1 Tue Nov 26 00:45:36 2019 DEPLOYED kong-1.0.0 1.0 ricinfra
+ r1-ricaux-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricaux
+ r1-ricinfra-credential 1 Tue Nov 26 00:45:43 2019 DEPLOYED credential-1.1.0 1.0 ricinfra
+ r1-ricplt-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricplt
+ r1-ricxapp-credential 1 Tue Nov 26 00:45:42 2019 DEPLOYED credential-1.1.0 1.0 ricxapp
+ r1-rsm 1 Tue Nov 26 00:47:15 2019 DEPLOYED rsm-2.0.6 1.0 ricplt
+ r1-rtmgr 1 Tue Nov 26 00:47:09 2019 DEPLOYED rtmgr-1.1.0 1.0 ricplt
+ r1-submgr 1 Tue Nov 26 00:47:13 2019 DEPLOYED submgr-1.1.0 1.0 ricplt
+ r1-vespamgr 1 Tue Nov 26 00:47:14 2019 DEPLOYED vespamgr-0.0.1 1.0 ricplt
+ r1-xapp-tiller 1 Tue Nov 26 00:45:44 2019 DEPLOYED xapp-tiller-0.1.0 1.0 ricinfra
+ # kubectl get pods -n ricplt
+ NAME READY STATUS RESTARTS AGE
+ deployment-ricplt-a1mediator-5c4df477f9-6zxxx 1/1 Running 0 132m
+ deployment-ricplt-appmgr-65bc8b958c-tggg7 1/1 Running 0 132m
+ deployment-ricplt-dbaas-74bf584449-k484v 1/1 Running 0 132m
+ deployment-ricplt-e2mgr-74cd9865bc-hpn6b 1/1 Running 0 132m
+ deployment-ricplt-e2term-cc7b5d99-pkctr 1/1 Running 0 132m
+ deployment-ricplt-jaegeradapter-cc49c64dc-vj622 1/1 Running 0 131m
+ deployment-ricplt-rsm-599cd4d6c8-4jhft 1/1 Running 0 131m
+ deployment-ricplt-rtmgr-85d89868d6-58wvl 1/1 Running 1 132m
+ deployment-ricplt-submgr-7cbd697c7f-p9x4x 1/1 Running 0 132m
+ deployment-ricplt-vespamgr-7bb4c7585f-9z6qm 1/1 Running 0 132m
+ # kubectl get pods -n ricinfra
+ NAME READY STATUS RESTARTS AGE
+ deployment-ricinfra-chartmuseum-7d97f4b995-gkxsq 1/1 Running 0 133m
+ deployment-tiller-ricxapp-65f9cbc8d7-qcr5t 1/1 Running 0 133m
+ r1-kong-kong-84695ff65d-9sjwg 2/2 Running 2 133m
+ tiller-secret-generator-w6bnd 0/1 Completed 0 133m
+
diff --git a/docs/installation-virtualbox.rst b/docs/installation-virtualbox.rst
new file mode 100644
index 0000000..30e029d
--- /dev/null
+++ b/docs/installation-virtualbox.rst
@@ -0,0 +1,83 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+
+
+Networking
+----------
+The set up requires two VMs connected by a private network. With VirtualBox, this can be done by going under its "Preferences" menu and set up a private NAT network.
+
+1. "Preference", then select the "Network" tab;
+2. Clicking on the "+" icon to create a new NAT network. A new entry will appear in the NAT networks list;
+3. Double clicking on the new network to edit its details, including giving int a name such as "RICNetwork";
+4. On the next page, make sure to check: "Enable Network", uncheck the "Supports DHCP" box, and make a note of the "Network CIDR" (for this example, it is 10.0.2.0/24);
+5. Click on the "Port Forwarding" button to create the following rules:
+
+ 1. "ssh to ric", TCP, 127.0.0.1, 22222, 10.0.2.100, 22;
+ 2. "ssh to aux", TCP, 127.0.0.1, 22223, 10.0.2.101, 22;
+ 3. "entry to ric", TCP, 127.0.0.1, 22224, 10.0.2.100, 32080;
+ 4. "entry to aux", TCP, 127.0.0.1, 22225, 10.0.2.101, 32080.
+
+6. "Ok" all the way back to create the network.
+
+
+Creating VMs
+-------------
+
+Create a VirtualBox VM:
+
+1. "New", then enter the following in the pop-up: Name it for example **myric**, of "Linux" type, and at least 4G RAM and 10G disk;
+2. "Create" to create the VM. It will appear in the list of VMs.
+3. Highlight the new VM entry, right click on it, select "Settings".
+
+ 1. Under the "System" tab, then "Processor" tab, make sure to give the VM at least 2 vCPUs.
+ 2. Under the "Storage" tab, point the CD to a Ubuntu 18.04 server ISO file;
+ 3. Under the "Network" tab, then "Adapter 1" tab, make sure to:
+
+ 1. Check "Enable Network Adapter";
+ 2. Attached to "NAT Network";
+ 3. Network name for what was created in the previous section: "RICNetwork".
+
+Repeat the process and create the second VM named **myaux**.
+
+
+Booting VM and OS Installation
+------------------------------
+
+Follow the OS installation steps to install OS to the VM virtual disk media. Make sure to install openssh server.
+
+
+VM Network Configuration
+-------------------------
+
+Depending on the version of the OS, the networking may be configured during the OS installation or after. The network interface is configured with static IP address:
+
+- IP Address: 10.0.2.100 for myric or 10.0.2.101 for myaux;
+- Network: 10.0.2.10/24, or network mask 255.255.255.0
+- Default gateway: 10.0.2.1
+- Name server: 8.8.8.8
+
+
+Accessing the VMs
+-----------------
+
+Because of the port forwarding configurations, the VMs are accessible from the VirtualBox host via ssh.
+
+- To access **myric**: ssh {{USERNAME}}@127.0.0.1 -p 22222
+- To access **myaux**: ssh {{USERNAME}}@127.0.0.1 -p 22223
+
+
diff --git a/docs/installation-xapps.rst b/docs/installation-xapps.rst
new file mode 100644
index 0000000..c42dc78
--- /dev/null
+++ b/docs/installation-xapps.rst
@@ -0,0 +1,83 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+Running the Near Realtime RIC
+==================================================================
+
+Loading xApp Helm Charts
+--------------------------
+
+The RIC Platform App Manager deploys RIC applications (a.k.a. xApps) using Helm charts stored in a private Helm repo. In the dev testing deployment described in this documentation, this private Helm repo is the Chart Museum pod that is deployed within the ric infrastructure group into the RIC cluster.
+
+The Helm repo location and credential for access the repo are specified in both the infrastructure and platform recipe files.
+
+Before any xApp can be deployed, its Helm chart must be loaded into this private Helm repo before the App manager can deploy them. The example below show a command sequence that completes:
+1. Add the Helm repo at the Helm client running on the RIC cluster host VM (via Kong Ingress Controller);
+2. Load the xApp Helm chart into the Helm repo;
+3. Update the local cache for the Helm repo and check the Helm chart is loaded;
+4. Calling App Manager to deploy the xApp;
+5. Calling App Manager to delete the xApp;
+6. Delete the xApp helm chart from the private Helm repo.
+
+.. code:: bash
+
+ # add the Chart Museum as repo cm
+ helm repo add cm http://10.0.2.100:32080/helm
+
+ # load admin-xapp Helm chart to the Chart Museum
+ curl -L -u helm:helm --data-binary "@admin-xapp-1.0.7.tgz" \
+ http://10.0.2.100:32080/helm/api/charts
+
+ # check the local cache of repo cm
+ helm repo update cm
+ # verify that the Helm chart is loaded and accessible
+ helm search cm/
+ # the new admin-app chart should show up here.
+
+ # test App Manager health check API
+ curl -v http://10.0.2.100:32080/appmgr/ric/v1/health/ready
+ # expecting a 200 response
+
+ # list deployed xApps
+ curl http://10.0.2.100:32080/appmgr/ric/v1/xapps
+ # expecting a []
+
+ # deploy xApp
+ curl -X POST http://10.0.2.100:32080/appmgr/ric/v1/xapps -d '{"name": "admin-xapp"}'
+ # expecting: {"name":"admin-app","status":"deployed","version":"1.0","instances":null}
+
+ # check again deployed xApp
+ curl http://10.0.2.10:32080/appmgr/ric/v1/xapps
+ # expecting a JSON array with an entry for admin-app
+
+ # check pods using kubectl
+ kubectl get pods --all-namespaces
+ # expecting the admin-xapp pod showing up
+
+ # underlay the xapp
+ curl -X DELETE http://10.0.2.100:32080/appmgr/ric/v1/xapps/admin-xapp
+
+ # check pods using kubectl
+ kubectl get pods --all-namespaces
+ # expecting the admin-xapp pod gone or shown as terminating
+
+ # to delete a chart
+ curl -L -X DELETE -u helm:helm http://10.0.2.100:32080/api/charts/admin-xapp/0.0.5
+
+For more xApp deployment and usage examples, please see documentations for the it/test repositooory.
+
+
diff --git a/docs/overview.rst b/docs/overview.rst
new file mode 100644
index 0000000..85c3d04
--- /dev/null
+++ b/docs/overview.rst
@@ -0,0 +1,31 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. ===============LICENSE_START=======================================================
+.. Copyright (C) 2019 AT&T Intellectual Property
+.. ===================================================================================
+.. This documentation file is distributed under the Creative Commons Attribution
+.. 4.0 International License (the "License"); you may not use this file except in
+.. compliance with the License. You may obtain a copy of the License at
+..
+.. http://creativecommons.org/licenses/by/4.0
+..
+.. This file is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+.. ===============LICENSE_END=========================================================
+
+Overview
+========
+
+The Amber Release of it/dep repositoy hosts deployment and integration artifacts such as scripts, Helm charts, and other files used for deploying O-RAN SC software.
+
+For Amber release this repo contains:
+
+- Deployment scripts for a dev-test 1-node Kubernetes cluster.
+- Deployment scripts and Helm charts for Near Realtime RAN Intelligent Controller Platform.
+- Deployment scripts and Helm charts for infrastructure services supporting the Near Realtime RAN Intelligent Controller Platform.
+- Deployment scripts and Helm charts for auxiliary services and components for operating the Near Realtime RAN Intelligent Controller Platform.
+
+
+
diff --git a/docs/user-guides.rst b/docs/user-guides.rst
deleted file mode 100644
index 2697e64..0000000
--- a/docs/user-guides.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. SPDX-License-Identifier: CC-BY-4.0
-.. ===============LICENSE_START=======================================================
-.. Copyright (C) 2019 AT&T Intellectual Property
-.. ===================================================================================
-.. This documentation file is distributed under the Creative Commons Attribution
-.. 4.0 International License (the "License"); you may not use this file except in
-.. compliance with the License. You may obtain a copy of the License at
-..
-.. http://creativecommons.org/licenses/by/4.0
-..
-.. This file is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-.. ===============LICENSE_END=========================================================
-
-.. contents::
- :depth: 3
- :local:
-
-.. a user guide should be how to use the component or system; it should not be a requirements document
-.. delete this content after edittng it
-
-
-Description
-=====================
-.. Describe the traget users of the projcet, for example, modeler/data scientist, ORAN-OSC platform admin, marketplace user, design studio end user, etc
-.. Descirbe how the target users can get use of a O-RAN SC component.
-.. If the guide contains sections on third-party tools, is it clearly stated why the O-RAN-OSC platform is using those tools? Are there instructions on how to install and configure each tool/toolset?
-
-Feature introduction
-================================
-.. Provide enough information that a user will be able to operate the feature on a deployed scenario. content can be added from administration, management, using, Troubleshooting sections perspectives.
-
-
-
-
-
