Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yadvr merged 6 commits into from
Sep 9, 2020
Merged

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

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4bde84f
Added basic and advanced customization sections to the primate doc
Jul 10, 2020
6c8910c
Additional changes
davidjumani Aug 7, 2020
82d8e44
Redirecting to github for advanced customization
davidjumani Aug 7, 2020
2d8d91a
minor fixes
davidjumani Aug 11, 2020
bef0870
Adding Basic Zone Deployment to missing features
davidjumani Aug 18, 2020
50b9ebe
Update primate.rst
yadvr Aug 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 118 additions & 42 deletions source/installguide/primate.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,6 @@
specific language governing permissions and limitations
under the License.

:ref:`primate-install-guide`

Primate Guide
=============

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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:

Expand All @@ -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