diff --git a/source/installguide/primate.rst b/source/installguide/primate.rst index bb01464bf9..d7bcbe42e9 100644 --- a/source/installguide/primate.rst +++ b/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 `_ 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 `_ +- Apache CloudStack 4.15 or later +- API discovery (listApis) enabled +- Modern browsers that are `ES5-compliant `_ -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 +`_ +repository. Advanced customisation may require some experience in JavaScript and VueJS, +a development and customisation guide is available `here +`_. + 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