Added basic and advanced customization sections to the primate doc (#142)

* Added basic and advanced customization sections to the primate doc

* Additional changes

* Redirecting to github for advanced customization

* minor fixes

* Adding Basic Zone Deployment to missing features

* Update primate.rst

Co-authored-by: Pearl Dsilva <pearl.dsilva@shapeblue.com>
Co-authored-by: davidjumani <dj.davidjumani1994@gmail.com>
Co-authored-by: Rohit Yadav <rohit.yadav@shapeblue.com>

Author: 4 people

source/installguide/primate.rst

@@ -13,8 +13,6 @@
    specific language governing permissions and limitations
    under the License.
 
-:ref:`primate-install-guide`
-
 Primate Guide
 =============
 
@@ -29,16 +27,8 @@ and Ant Design for Apache CloudStack.
    :alt: alternate text
    :align: left
 
-With Apache CloudStack 4.14, a technical preview of Primate is proposed that
-users can evaluate. The technical preview release is not an officially voted
-release by the Apache CloudStack project but offers a snapshot build of Primate
-for users for testing and evaluation. The official Primate GA is expected with
-the next CloudStack release where the legacy UI will be deprecated, and the
-legacy UI will be removed in an eventual major CloudStack release.
-
-.. parsed-literal::
-
-    NOTE: Primate tech-preview is not suitable to run in production environments.
+Primate GA was released with CloudStack 4.15, where the legacy UI is deprecated,
+and will be removed in an eventual major CloudStack release.
 
 `User participation in the community mailing lists
 <http://cloudstack.apache.org/mailing-lists.html>`_ is encouraged. Users may
@@ -48,29 +38,30 @@ Requirements
 ~~~~~~~~~~~~
 
 Primate uses API auto-discovery to discover APIs allowed for a logged-in user
-and creates navigation and views based on that.
+and creates navigation and views based on that, and requires the following:
 
-- Apache CloudStack 4.13.1.0 or later
-- API auto-discovery (listApis enabled)
-- All modern browsers that are `ES5-compliant <https://github.com/vuejs/vue#browser-compatibility>`_
+- Apache CloudStack 4.15 or later
+- API discovery (listApis) enabled
+- Modern browsers that are `ES5-compliant <https://github.com/vuejs/vue#browser-compatibility>`_
 
-In theory Primate can work with any older version of CloudStack.
-However, several Primate list views require API pagination support, some of which are
-available starting Apache CloudStack 4.13.1.0.
+In theory Primate can work with any older version of CloudStack that supports
+API discovery. However, several Primate list views require API pagination support,
+some of which are available starting Apache CloudStack 4.15 as well as several other
+API improvements which may not be available prior to Apache CloudStack 4.15.
 
 Installation on CentOS
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Users running management server (4.13 or above) on CentOS can setup the
-following Primate tech-preview repository:
+Users running management server (4.15 or above) on CentOS can setup the
+following Primate repository:
 
 .. parsed-literal::
 
     rpm --import https://download.cloudstack.org/primate/release.asc
-    cat << EOF > /etc/yum.repos.d/cloudstack-primate-tech-preview.repo
-    [cloudstack-primate-tech-preview]
+    cat << EOF > /etc/yum.repos.d/cloudstack-primate.repo
+    [cloudstack-primate]
     name=cloudstack
-    baseurl=https://download.cloudstack.org/primate/testing/preview/centos/
+    baseurl=https://download.cloudstack.org/primate/centos/
     enabled=1
     gpgcheck=1
     gpgkey=https://download.cloudstack.org/primate/release.asc
@@ -89,12 +80,12 @@ management-server-host:8080/client/primate using any modern browser.
 Installation on Ubuntu
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Users running CloudStack management server (4.13 or above) on Ubuntu can setup the following Primate tech-preview repository:
+Users running CloudStack management server (4.15 or above) on Ubuntu can setup the following Primate repository:
 
 .. parsed-literal::
 
     apt-key adv --keyserver keys.gnupg.net --recv-keys BDF0E176584DF93F
-    echo deb https://download.cloudstack.org/primate/testing/preview/debian / > /etc/apt/sources.list.d/cloudstack-primate-tech-preview.list
+    echo deb https://download.cloudstack.org/primate/debian / > /etc/apt/sources.list.d/cloudstack-primate.list
 
 Next, install Primate:
 
@@ -114,19 +105,19 @@ Primate archives are tarballs of single-page app builds. They can be simply
 downloaded and extracted to the management server webapp directory or hosted
 with a custom webserver.
 
-Users can download the builds from https://download.cloudstack.org/primate/testing/preview/archive/
+Users can download the builds from https://download.cloudstack.org/primate/archive/
 
 Using Docker
 ~~~~~~~~~~~~
 
-Users can use docker builds of the tech preview from https://hub.docker.com/r/apache/cloudstack-primate
+Users can use docker builds of Primate from https://hub.docker.com/r/apache/cloudstack-primate
 
 For example:
 
 .. parsed-literal::
 
-    docker pull apache/cloudstack-primate:tech-preview
-    docker run -ti --rm -p 8080:80 -v $(pwd)/nginx:/etc/nginx/conf.d:ro apache/cloudstack-primate:tech-preview
+    docker pull apache/cloudstack-primate:latest
+    docker run -ti --rm -p 8080:80 -v $(pwd)/nginx:/etc/nginx/conf.d:ro apache/cloudstack-primate:latest
 
 Example nginx config:
 
@@ -146,18 +137,103 @@ Example nginx config:
         }
     }
 
+Basic Customization in CloudStack Primate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Users can now customize the CloudStack's user interface by means of a configuration file at /usr/share/cloudstack-management/webapp/primate/config.json which can be used to modify the theme, logos, etc. to align to one's requirement.
+
+To change the logo, login banner, error page icon, etc. the following details can be edited in config.json:
+
+.. parsed-literal::
+
+    "logo": "assets/logo.svg",
+    "banner": "assets/banner.svg",
+    "error": {
+        "404": "assets/404.png",
+        "403": "assets/403.png",
+        "500": "assets/500.png"
+    }
+
+where,
+
+- logo: changes the logo top-left side image.
+- banner: changes the login banner image.
+- error.404: changes the image of error Page not found.
+- error.403: changes the image of error Forbidden.
+- error.500: changes the image of error Internal Server Error.
+
+Customization of themes is also possible, such as, modifying banner width, general color, etc. This can be done by editing the "theme" section of the config.json file:
+
+.. parsed-literal::
+
+    "theme": {
+        "@primary-color": "#1890ff",
+        "@link-color": "#1890ff",
+        "@processing-color": "#1890ff",
+        "@success-color": "#52c41a",
+        "@warning-color": "#faad14",
+        "@error-color": "#f5222d",
+        "@font-size-base": "14px",
+        "@heading-color": "rgba(0, 0, 0, 0.85)",
+        "@text-color": "rgba(0, 0, 0, 0.65)",
+        "@text-color-secondary": "rgba(0, 0, 0, 0.45)",
+        "@disabled-color": "rgba(0, 0, 0, 0.25)",
+        "@border-color-base": "#d9d9d9",
+        "@border-radius-base": "4px",
+        "@box-shadow-base": "0 2px 8px rgba(0, 0, 0, 0.15)",
+        "@logo-width": "256px",
+        "@logo-height": "64px",
+        "@banner-width": "700px",
+        "@banner-height": "110px",
+        "@error-width": "256px",
+        "@error-height": "256px"
+    }
+
+where,
+
+- @primary-color: changes the major background color of the page (background button, icon hover, etc).
+- @success-color: changes success state color.
+- @processing-color: changes processing state color. Exp: progress status.
+- @warning-color: changes warning state color.
+- @error-color: changes error state color.
+- @heading-color: changes table header color.
+- @text-color: change in major text color.
+- @text-color-secondary: change of secondary text color (breadcrumb icon).
+- @disabled-color: disable state color (disabled button, switch, etc).
+- @border-color-base: change in major border color.
+- @logo-width: change the width of the logo top-left side.
+- @logo-height: change the height of the logo top-left side.
+- @banner-width: changes the width of the login banner.
+- @banner-height: changes the height of the login banner.
+- @error-width: changes the width of the error image.
+- @error-height: changes the height of the error image.
+
+Some assorted primary theme colours:
+
+- Blue: #1890FF
+- Red: #F5222D
+- Yellow: #FAAD14
+- Cyan: #13C2C2
+- Green: #52C41A
+- Purple: #722ED1
+
+Advanced Customisation
+~~~~~~~~~~~~~~~~~~~~~~
+
+Primate advanced customisation is possible only by changing JavaScript based config
+files which define rules for sections, names, icons, actions and components and by
+building primate from source available on the `cloudstack-primate
+<https://github.com/apache/cloudstack-primate>`_
+repository. Advanced customisation may require some experience in JavaScript and VueJS,
+a development and customisation guide is available `here
+<https://github.com/apache/cloudstack-primate/blob/master/docs/development.md>`_.
+
 Known Issues and Missing Features
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Support for network service providers
-- Support for S3 based secondary storage
-- Full support for all Quota plugin views
-- Group actions for events, alerts and instances
-- Metrics view cell-colouring
-- Authorisation management for SAML users
-- Filter by feature for searching
-- Guest network LB support for SSL certificate
-- Not all translations are fully migrated from legacy UI to Primate.
-- Feature and enhancements added in 4.14 except CloudStack Kubernetes Service and Backup and Recovery
-
-Please also refer to open issues on https://github.com/apache/cloudstack-primate/issues
+- Deployment of a basic zone is not supported. However, existing basic zones will continue to be supported as well as all the actions and views of various resources within the existing basic zone.
+- Support for S3 based secondary storage.
+- NFS secondary staging storage list/resource view and add/update actions.
+- SSL certificate for Guest network LB rule.
+- Regions.
+
+Primate open issues are listed on https://github.com/apache/cloudstack-primate/issues