re-org of the installation guide
Change-Id: Ib3e0b83cca3a97b1ee0f1719f0d56f554832b4f6
diff --git a/README.md b/README.md
index ffadeed..87b8637 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,15 @@
# Installation Guide
-This guide describes how to install CORD.
-
-## Prerequisites
-
-Start by satisfying the following prerequisites:
-
-* [Hardware Requirements](./prereqs/hardware.md)
-* [Connectivity Requirements](./prereqs/networking.md)
-* [Software Requirements](./prereqs/software.md)
-
-## Deploy CORD
-
-The next step is select the configuration (profile) you want to
-install:
+This guide describes how to install CORD. It identifies a set of
+[prerequisites](prereqs/README.md), and then walks through
+the steps involved in bringing up one of two CORD profiles:
* [R-CORD](./profiles/rcord/install.md)
* [M-CORD](./profiles/mcord/install.md)
-## Additional Information
+If you are anxious to jump straight to a [Quick Start](quickstart.md)
+procedure that brings up the an emulated version of CORD running
+on your laptop (sorry, no subscriber data plane), then that's an option.
-The following are optional steps you may want to take
-
-### Offline Installation
-
-If your environment does not permit connecin your POD to ther public
-Internet, you may want to take advantage of a local Docker registery.
-The following [registry setup](./prereqs/docker-registry.md) will help.
-
-### OpenStack Installation
-
-If you need OpenStack included in your deployment, so you can bring up
-VMs on your POD, you will need to following the following
-[OpenStack deployment](./prereqs/openstack-helm.md) guide.
+Alternatively, if you want to get a broader layof-of-the-land, you
+might step back and start with an [Overview](overview.md).
diff --git a/SUMMARY.md b/SUMMARY.md
index 0274795..2950f39 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -2,17 +2,20 @@
* [Overview](overview.md)
* [Navigating the Guide](navigate.md)
+ * [Quick Start](quickstart.md)
* [Installation Guide](README.md)
- * [Hardware Requirements](prereqs/hardware.md)
- * [Connectivity Requirements](prereqs/networking.md)
- * [Software Requirements](prereqs/software.md)
- * [Kubernetes](prereqs/kubernetes.md)
- * [Single Node](prereqs/k8s-single-node.md)
- * [Multi-Node](prereqs/k8s-multi-node.md)
- * [Helm](prereqs/helm.md)
- * [Docker Registry (optional)](prereqs/docker-registry.md)
- * [OpenStack (optional)](prereqs/openstack-helm.md)
- * [Fabric Setup](fabric-setup.md)
+ * [Prerequisites](prereqs/README.md)
+ * [Hardware Requirements](prereqs/hardware.md)
+ * [Connectivity Requirements](prereqs/networking.md)
+ * [Software Requirements](prereqs/software.md)
+ * [Kubernetes](prereqs/kubernetes.md)
+ * [Single Node](prereqs/k8s-single-node.md)
+ * [Multi-Node](prereqs/k8s-multi-node.md)
+ * [Helm](prereqs/helm.md)
+ * [Optional Packages](prereqs/optional.md)
+ * [Docker Registry](prereqs/docker-registry.md)
+ * [OpenStack](prereqs/openstack-helm.md)
+ * [Fabric Software Setup](fabric-setup.md)
* [Bringing Up CORD](profiles/intro.md)
* [R-CORD](profiles/rcord/install.md)
* [OLT Setup](openolt/README.md)
@@ -48,12 +51,13 @@
* [Getting the Source Code](developer/getting_the_code.md)
* [Writing Models and Synchronizers](xos/README.md)
* [XOS Modeling Framework](xos/dev/xproto.md)
+ * [XOS Tool Chain (Internals)](xos/dev/xosgenx.md)
+ * [XOS Synchronizer Framework](xos/dev/synchronizers.md)
+ * [Synchronizer Design](xos/dev/sync_arch.md)
+ * [Synchronizer Implementation](xos/dev/sync_impl.md)
+ * [Synchronizer Reference](xos/dev/sync_reference.md)
* [Core Models](xos/core_models.md)
* [Security Policies](xos/security_policies.md)
- * [Writing Synchronizers](xos/dev/synchronizers.md)
- * [Design Guidelines](xos/dev/sync_arch.md)
- * [Implementation Details](xos/dev/sync_impl.md)
- * [Synchronizer Reference](xos/dev/sync_reference.md)
* [Developer Workflows](developer/workflows.md)
* [Building Docker Images](developer/imagebuilder.md)
* [Platform Services](developer/platform.md)
diff --git a/charts/helm.md b/charts/helm.md
index a4c68ff..63ce16f 100644
--- a/charts/helm.md
+++ b/charts/helm.md
@@ -1,11 +1,10 @@
# Helm Reference
-For information on how to install `helm` please refer to [Installing helm](../prereqs/helm.md)
-
-## What is Helm?
-
{% include "/partials/helm/description.md" %}
+For information on how to install `helm` please refer to
+[Installing Helm](../prereqs/helm.md).
+
## CORD Helm Charts
All helm charts used to install CORD can be found in the `helm-chart`
diff --git a/fabric-setup.md b/fabric-setup.md
index e4f0d2d..dfe98e3 100644
--- a/fabric-setup.md
+++ b/fabric-setup.md
@@ -1,31 +1,33 @@
-# Fabric switches software setup
+# Fabric Software Setup
CORD uses the Trellis fabric to connect the data plane components together.
+This section describes how to setup the software for these switches.
-The full [latest Trellis fabric documentation](https://wiki.opencord.org/display/CORD/Trellis%3A+CORD+Network+Infrastructure) can still be found on the old CORD wiki.
+The latest [Trellis Fabric](https://wiki.opencord.org/display/CORD/Trellis%3A+CORD+Network+Infrastructure) documentation can be found on the CORD wiki.
-## Supported switches
+## Supported Switches
-The list of supported hardware can be found in the [hardware requirements page](prereqs/hardware.html#generic-hardware-guidelines).
+The list of supported hardware can be found in the [hardware requirements page](prereqs/hardware.md).
-## Operating system
+## Operating System
-At today, all compatible switches use [Open Networking Linux (ONL)](https://opennetlinux.org/) as operating system.
-
+All CORD-compatible switches use [Open Networking Linux (ONL)](https://opennetlinux.org/) as operating system.
The [latest compatible ONL image](https://github.com/opencord/OpenNetworkLinux/releases/download/2017-10-19.2200-1211610/ONL-2.0.0_ONL-OS_2017-10-19.2200-1211610_AMD64_INSTALLED_INSTALLER) can be downloaded from [here](https://github.com/opencord/OpenNetworkLinux/releases/download/2017-10-19.2200-1211610/ONL-2.0.0_ONL-OS_2017-10-19.2200-1211610_AMD64_INSTALLED_INSTALLER).
**Checksum**: *sha256:2db316ea83f5dc761b9b11cc8542f153f092f3b49d82ffc0a36a2c41290f5421*
-Deployment guidelines on how to install ONL on top of an ONIE compatible device can be found directly on the [ONL website](https://opennetlinux.org/docs/deploy).
+Guidelines on how to install ONL on top of an ONIE compatible device can be found directly on the [ONL website](https://opennetlinux.org/docs/deploy).
-This specific version of ONL has been already customized to accept an IP address through DHCP on the management interface, *ma0*. If you'd like to use a static IP, give it first an IP through DHCP, login and change the configuration in */etc/network/interfaces*.
+This specific version of ONL has been customized to accept an IP address through DHCP on the management interface, *ma0*. If you'd like to use a static IP, first give
+it an IP address through DHCP, then login and change the configuration in
+*/etc/network/interfaces*.
The default *username* and *password* are *root* / *onl*.
-## OFDPA drivers
+## OFDPA Drivers
Once ONL is installed OFDPA drivers will need to be installed as well.
-Each switch model requires a specific version of OFDPA. All driver packages are distributed as DEB packages. This makes the installation process very easy.
+Each switch model requires a specific version of OFDPA. All driver packages are distributed as DEB packages, which makes the installation process straightforward.
First, copy the package to the switch. For example
@@ -33,13 +35,13 @@
scp your-ofdpa.deb root@fabric-switch-ip:
```
-Then, install the deb package
+Then, install the DEB package
```shell
dpkg -i your-ofdpa.deb
```
-## OFDPA drivers download
+Two OFDPA drivers are available:
* [EdgeCore 5712-54X / 5812-54X / 6712-32X](https://github.com/onfsdn/atrium-docs/blob/master/16A/ONOS/builds/ofdpa_3.0.5.5%2Baccton1.7-1_amd64.deb?raw=true) - *checksum: sha256:db228b6e79fb15f77497b59689235606b60abc157e72fc3356071bcc8dc4c01f*
* [QuantaMesh T3048-LY8](https://github.com/onfsdn/atrium-docs/blob/master/16A/ONOS/builds/ofdpa-ly8_0.3.0.5.0-EA5-qct-01.01_amd64.deb?raw=true) - *checksum: sha256:f8201530b1452145c1a0956ea1d3c0402c3568d090553d0d7b3c91a79137da9e*
diff --git a/partials/helm/description.md b/partials/helm/description.md
index 383710a..1c04574 100644
--- a/partials/helm/description.md
+++ b/partials/helm/description.md
@@ -1,5 +1,3 @@
Helm is the package manager for Kubernetes. It lets you define, install,
-and upgrade Kubernetes base application.
-
-For more informations about helm,
-please the visit the official website: <https://helm.sh>
\ No newline at end of file
+and upgrade Kubernetes base application. For more information about Helm,
+please the visit the official website: <https://helm.sh>.
diff --git a/prereqs/README.md b/prereqs/README.md
new file mode 100644
index 0000000..9195069
--- /dev/null
+++ b/prereqs/README.md
@@ -0,0 +1,12 @@
+# Prerequisites
+
+The latest release of CORD decouples setting up the deployment environment from
+installing CORD. This means more prerequisites must be satisfied (as enumerated
+in this section), but doing so provides more latitude in how you prep a POD to best
+match your local environment.
+
+There are three categories of requirements that must be met before installing CORD:
+
+* [Hardware Requirements](hardware.md)
+* [Connectivity Requirements](networking.md)
+* [Software Requirements](software.md)
diff --git a/prereqs/docker-registry.md b/prereqs/docker-registry.md
index 2b7c74d..8290700 100644
--- a/prereqs/docker-registry.md
+++ b/prereqs/docker-registry.md
@@ -1,4 +1,4 @@
-# Docker Registry (optional)
+# Docker Registry
The section describes how to install an **insecure** *docker registry* in Kubernetes, using the standard Kubernetes helm charts.
diff --git a/prereqs/kubernetes.md b/prereqs/kubernetes.md
index 7a3e3d0..e840b38 100644
--- a/prereqs/kubernetes.md
+++ b/prereqs/kubernetes.md
@@ -51,8 +51,3 @@
If you've just installed Kubernetes, likely you won't see any pod, yet.
That's fine, as long as you don't see errors.
-## Install Helm
-
-CORD uses a tool called Helm to deploy containers on Kubernetes.
-As such, Helm needs to be installed before being able to deploy CORD containers.
-More info on Helm and how to install it can be found [here](helm.md).
diff --git a/prereqs/openstack-helm.md b/prereqs/openstack-helm.md
index 74dc8cd..4fa20d4 100644
--- a/prereqs/openstack-helm.md
+++ b/prereqs/openstack-helm.md
@@ -1,4 +1,4 @@
-# OpenStack (optional)
+# OpenStack
The [openstack-helm](https://github.com/openstack/openstack-helm)
project can be used to install a set of Kubernetes nodes as OpenStack
diff --git a/prereqs/optional.md b/prereqs/optional.md
new file mode 100644
index 0000000..2681b30
--- /dev/null
+++ b/prereqs/optional.md
@@ -0,0 +1,14 @@
+# Optional Packages
+
+Although not required, you may want to install one or both of the following
+packages:
+
+* **Local Registry:** If your environment does not permit connecing your
+ POD to ther public Internet, you may want to take advantage of a local Docker
+ registery. The following [registry setup](docker-registry.md) will help.
+ (Having a local registry is also useful when doing local development, as outlined
+ in the [Developer Guide](../developer/workflows.md).)
+
+* **OpenStack:** If you need to include OpenStack in your deployment,
+ so you can bring up VMs on your POD, you will need to following the
+ [OpenStack deployment](openstack-helm.md) guide.
diff --git a/quickstart.md b/quickstart.md
new file mode 100644
index 0000000..b42cf11
--- /dev/null
+++ b/quickstart.md
@@ -0,0 +1,8 @@
+# Quick Start
+
+This section walks you through the installation sequence to bring up a
+demonstration configuration of CORD that includes a simple example
+service. If you'd prefer to understand the installation process in more
+depth, you might start with the [Installation Guide](README.md).
+
+More to come...