diff --git a/doc/source/install/deploy-guide.rst b/doc/source/install/from-source.rst similarity index 98% rename from doc/source/install/deploy-guide.rst rename to doc/source/install/from-source.rst index 663cd615b9..37d9406879 100644 --- a/doc/source/install/deploy-guide.rst +++ b/doc/source/install/from-source.rst @@ -1,6 +1,6 @@ -================================ -Installing and Deploying Horizon -================================ +=================== +Manual installation +=================== This page covers the basic installation of horizon in a production environment. If you are looking for a developer enviroment, see diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 02dae6b2db..3e07d00470 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -2,13 +2,38 @@ Deployment & Configuration ========================== -This section provides instruction on configuring and deploying Horizon and its -plugins. +This section describes how to install and configure the dashboard +on the controller node. + +The only core service required by the dashboard is the Identity service. +You can use the dashboard in combination with other services, such as +Image service, Compute, and Networking. You can also use the dashboard +in environments with stand-alone services such as Object Storage. + +.. note:: + + This section assumes proper installation, configuration, and operation + of the Identity service using the Apache HTTP server and Memcached + service. + +Installing from Packages +======================== + +.. toctree:: + :maxdepth: 1 + :glob: + + install-* + verify-* + next-steps + +Installing from Source +====================== .. toctree:: :maxdepth: 1 - deploy-guide.rst + from-source.rst settings.rst customizing.rst plugin-registry.rst diff --git a/doc/source/install/install-debian.rst b/doc/source/install/install-debian.rst new file mode 100644 index 0000000000..47887dbc06 --- /dev/null +++ b/doc/source/install/install-debian.rst @@ -0,0 +1,212 @@ +================================ +Install and configure for Debian +================================ + +This section describes how to install and configure the dashboard +on the controller node. + +The only core service required by the dashboard is the Identity service. +You can use the dashboard in combination with other services, such as +Image service, Compute, and Networking. You can also use the dashboard +in environments with stand-alone services such as Object Storage. + +.. note:: + + This section assumes proper installation, configuration, and operation + of the Identity service using the Apache HTTP server and Memcached + service. + +Install and configure components +-------------------------------- + +.. include:: note_configuration_vary_by_distribution.txt + + + + + +1. Install the packages: + + .. code-block:: console + + # apt install openstack-dashboard-apache + + .. end + +2. Respond to prompts for web server configuration. + + .. note:: + + The automatic configuration process generates a self-signed + SSL certificate. Consider obtaining an official certificate + for production environments. + + .. note:: + + There are two modes of installation. One using ``/horizon`` as the URL, + keeping your default vhost and only adding an Alias directive: this is + the default. The other mode will remove the default Apache vhost and install + the dashboard on the webroot. It was the only available option + before the Liberty release. If you prefer to set the Apache configuration + manually, install the ``openstack-dashboard`` package instead of + ``openstack-dashboard-apache``. + + + + + +2. Edit the + ``/etc/openstack-dashboard/local_settings.py`` + file and complete the following actions: + + * Configure the dashboard to use OpenStack services on the + ``controller`` node: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_HOST = "controller" + + .. end + + * In the Dashboard configuration section, allow your hosts to access + Dashboard: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + ALLOWED_HOSTS = ['one.example.com', 'two.example.com'] + + .. end + + .. note:: + + - Do not edit the ``ALLOWED_HOSTS`` parameter under the Ubuntu + configuration section. + - ``ALLOWED_HOSTS`` can also be ``['*']`` to accept all hosts. This + may be useful for development work, but is potentially insecure + and should not be used in production. See the + `Django documentation + `_ + for further information. + + * Configure the ``memcached`` session storage service: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + SESSION_ENGINE = 'django.contrib.sessions.backends.cache' + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', + 'LOCATION': 'controller:11211', + } + } + + .. end + + .. note:: + + Comment out any other session storage configuration. + + * Enable the Identity API version 3: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_URL = "http://%s:5000/v3" % OPENSTACK_HOST + + .. end + + * Enable support for domains: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT = True + + .. end + + * Configure API versions: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_API_VERSIONS = { + "identity": 3, + "image": 2, + "volume": 2, + } + + .. end + + * Configure ``Default`` as the default domain for users that you create + via the dashboard: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_DOMAIN = "Default" + + .. end + + * Configure ``user`` as the default role for + users that you create via the dashboard: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_ROLE = "user" + + .. end + + * If you chose networking option 1, disable support for layer-3 + networking services: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_NEUTRON_NETWORK = { + ... + 'enable_router': False, + 'enable_quotas': False, + 'enable_ipv6': False, + 'enable_distributed_router': False, + 'enable_ha_router': False, + 'enable_lb': False, + 'enable_firewall': False, + 'enable_vpn': False, + 'enable_fip_topology_check': False, + } + + .. end + + * Optionally, configure the time zone: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + TIME_ZONE = "TIME_ZONE" + + .. end + + Replace ``TIME_ZONE`` with an appropriate time zone identifier. + For more information, see the `list of time zones + `__. + + +Finalize installation +--------------------- + + +* Reload the web server configuration: + + .. code-block:: console + + # service apache2 reload + + .. end + + + diff --git a/doc/source/install/install-obs.rst b/doc/source/install/install-obs.rst new file mode 100644 index 0000000000..4794dc6192 --- /dev/null +++ b/doc/source/install/install-obs.rst @@ -0,0 +1,204 @@ +============================================================ +Install and configure for openSUSE and SUSE Linux Enterprise +============================================================ + +This section describes how to install and configure the dashboard +on the controller node. + +The only core service required by the dashboard is the Identity service. +You can use the dashboard in combination with other services, such as +Image service, Compute, and Networking. You can also use the dashboard +in environments with stand-alone services such as Object Storage. + +.. note:: + + This section assumes proper installation, configuration, and operation + of the Identity service using the Apache HTTP server and Memcached + service. + +Install and configure components +-------------------------------- + +.. include:: note_configuration_vary_by_distribution.txt + + +1. Install the packages: + + .. code-block:: console + + # zypper install openstack-dashboard + + .. end + + + + + + +2. Configure the web server: + + .. code-block:: console + + # cp /etc/apache2/conf.d/openstack-dashboard.conf.sample \ + /etc/apache2/conf.d/openstack-dashboard.conf + # a2enmod rewrite + + .. end + +3. Edit the + ``/srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py`` + file and complete the following actions: + + * Configure the dashboard to use OpenStack services on the + ``controller`` node: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_HOST = "controller" + + .. end + + * Allow your hosts to access the dashboard: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + ALLOWED_HOSTS = ['one.example.com', 'two.example.com'] + + .. end + + .. note:: + + ``ALLOWED_HOSTS`` can also be ``['*']`` to accept all hosts. This may be + useful for development work, but is potentially insecure and should + not be used in production. See `Django documentation + `_ + for further information. + + * Configure the ``memcached`` session storage service: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + SESSION_ENGINE = 'django.contrib.sessions.backends.cache' + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', + 'LOCATION': 'controller:11211', + } + } + + .. end + + .. note:: + + Comment out any other session storage configuration. + + * Enable the Identity API version 3: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_URL = "http://%s:5000/v3" % OPENSTACK_HOST + + .. end + + * Enable support for domains: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT = True + + .. end + + * Configure API versions: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_API_VERSIONS = { + "identity": 3, + "image": 2, + "volume": 2, + } + + .. end + + * Configure ``Default`` as the default domain for users that you create + via the dashboard: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_DOMAIN = "Default" + + .. end + + * Configure ``user`` as the default role for + users that you create via the dashboard: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_ROLE = "user" + + .. end + + * If you chose networking option 1, disable support for layer-3 + networking services: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + OPENSTACK_NEUTRON_NETWORK = { + ... + 'enable_router': False, + 'enable_quotas': False, + 'enable_distributed_router': False, + 'enable_ha_router': False, + 'enable_lb': False, + 'enable_firewall': False, + 'enable_vpn': False, + 'enable_fip_topology_check': False, + } + + .. end + + * Optionally, configure the time zone: + + .. path /srv/www/openstack-dashboard/openstack_dashboard/local/local_settings.py + .. code-block:: python + + TIME_ZONE = "TIME_ZONE" + + .. end + + Replace ``TIME_ZONE`` with an appropriate time zone identifier. + For more information, see the `list of time zones + `__. + + + + +Finalize installation +--------------------- + + + +* Restart the web server and session storage service: + + .. code-block:: console + + # systemctl restart apache2.service memcached.service + + .. end + + .. note:: + + The ``systemctl restart`` command starts each service if + not currently running. + + diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst new file mode 100644 index 0000000000..a58bca0649 --- /dev/null +++ b/doc/source/install/install-rdo.rst @@ -0,0 +1,194 @@ +============================================================= +Install and configure for Red Hat Enterprise Linux and CentOS +============================================================= + +This section describes how to install and configure the dashboard +on the controller node. + +The only core service required by the dashboard is the Identity service. +You can use the dashboard in combination with other services, such as +Image service, Compute, and Networking. You can also use the dashboard +in environments with stand-alone services such as Object Storage. + +.. note:: + + This section assumes proper installation, configuration, and operation + of the Identity service using the Apache HTTP server and Memcached + service. + +Install and configure components +-------------------------------- + +.. include:: note_configuration_vary_by_distribution.txt + + + +1. Install the packages: + + .. code-block:: console + + # yum install openstack-dashboard + + .. end + + + + + + +2. Edit the + ``/etc/openstack-dashboard/local_settings`` + file and complete the following actions: + + * Configure the dashboard to use OpenStack services on the + ``controller`` node: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_HOST = "controller" + + .. end + + * Allow your hosts to access the dashboard: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + ALLOWED_HOSTS = ['one.example.com', 'two.example.com'] + + .. end + + .. note:: + + ALLOWED_HOSTS can also be ['*'] to accept all hosts. This may be + useful for development work, but is potentially insecure and should + not be used in production. See + https://docs.djangoproject.com/en/dev/ref/settings/#allowed-hosts + for further information. + + * Configure the ``memcached`` session storage service: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + SESSION_ENGINE = 'django.contrib.sessions.backends.cache' + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', + 'LOCATION': 'controller:11211', + } + } + + .. end + + .. note:: + + Comment out any other session storage configuration. + + * Enable the Identity API version 3: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_KEYSTONE_URL = "http://%s:5000/v3" % OPENSTACK_HOST + + .. end + + * Enable support for domains: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT = True + + .. end + + * Configure API versions: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_API_VERSIONS = { + "identity": 3, + "image": 2, + "volume": 2, + } + + .. end + + * Configure ``Default`` as the default domain for users that you create + via the dashboard: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_DOMAIN = "Default" + + .. end + + * Configure ``user`` as the default role for + users that you create via the dashboard: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_ROLE = "user" + + .. end + + * If you chose networking option 1, disable support for layer-3 + networking services: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + OPENSTACK_NEUTRON_NETWORK = { + ... + 'enable_router': False, + 'enable_quotas': False, + 'enable_distributed_router': False, + 'enable_ha_router': False, + 'enable_lb': False, + 'enable_firewall': False, + 'enable_vpn': False, + 'enable_fip_topology_check': False, + } + + .. end + + * Optionally, configure the time zone: + + .. path /etc/openstack-dashboard/local_settings + .. code-block:: python + + TIME_ZONE = "TIME_ZONE" + + .. end + + Replace ``TIME_ZONE`` with an appropriate time zone identifier. + For more information, see the `list of time zones + `__. + + + +Finalize installation +--------------------- + + + + +* Restart the web server and session storage service: + + .. code-block:: console + + # systemctl restart httpd.service memcached.service + + .. end + + .. note:: + + The ``systemctl restart`` command starts each service if + not currently running. + diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst new file mode 100644 index 0000000000..06f4853575 --- /dev/null +++ b/doc/source/install/install-ubuntu.rst @@ -0,0 +1,194 @@ +================================ +Install and configure for Ubuntu +================================ + +This section describes how to install and configure the dashboard +on the controller node. + +The only core service required by the dashboard is the Identity service. +You can use the dashboard in combination with other services, such as +Image service, Compute, and Networking. You can also use the dashboard +in environments with stand-alone services such as Object Storage. + +.. note:: + + This section assumes proper installation, configuration, and operation + of the Identity service using the Apache HTTP server and Memcached + service. + +Install and configure components +-------------------------------- + +.. include:: note_configuration_vary_by_distribution.txt + + + + +1. Install the packages: + + .. code-block:: console + + # apt install openstack-dashboard + + .. end + + + + + + +2. Edit the + ``/etc/openstack-dashboard/local_settings.py`` + file and complete the following actions: + + * Configure the dashboard to use OpenStack services on the + ``controller`` node: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_HOST = "controller" + + .. end + + * In the Dashboard configuration section, allow your hosts to access + Dashboard: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + ALLOWED_HOSTS = ['one.example.com', 'two.example.com'] + + .. end + + .. note:: + + - Do not edit the ``ALLOWED_HOSTS`` parameter under the Ubuntu + configuration section. + - ``ALLOWED_HOSTS`` can also be ``['*']`` to accept all hosts. This + may be useful for development work, but is potentially insecure + and should not be used in production. See the + `Django documentation + `_ + for further information. + + * Configure the ``memcached`` session storage service: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + SESSION_ENGINE = 'django.contrib.sessions.backends.cache' + + CACHES = { + 'default': { + 'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache', + 'LOCATION': 'controller:11211', + } + } + + .. end + + .. note:: + + Comment out any other session storage configuration. + + * Enable the Identity API version 3: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_URL = "http://%s:5000/v3" % OPENSTACK_HOST + + .. end + + * Enable support for domains: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_MULTIDOMAIN_SUPPORT = True + + .. end + + * Configure API versions: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_API_VERSIONS = { + "identity": 3, + "image": 2, + "volume": 2, + } + + .. end + + * Configure ``Default`` as the default domain for users that you create + via the dashboard: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_DOMAIN = "Default" + + .. end + + * Configure ``user`` as the default role for + users that you create via the dashboard: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_KEYSTONE_DEFAULT_ROLE = "user" + + .. end + + * If you chose networking option 1, disable support for layer-3 + networking services: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + OPENSTACK_NEUTRON_NETWORK = { + ... + 'enable_router': False, + 'enable_quotas': False, + 'enable_ipv6': False, + 'enable_distributed_router': False, + 'enable_ha_router': False, + 'enable_lb': False, + 'enable_firewall': False, + 'enable_vpn': False, + 'enable_fip_topology_check': False, + } + + .. end + + * Optionally, configure the time zone: + + .. path /etc/openstack-dashboard/local_settings.py + .. code-block:: python + + TIME_ZONE = "TIME_ZONE" + + .. end + + Replace ``TIME_ZONE`` with an appropriate time zone identifier. + For more information, see the `list of time zones + `__. + + +Finalize installation +--------------------- + + +* Reload the web server configuration: + + .. code-block:: console + + # service apache2 reload + + .. end + + + diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst new file mode 100644 index 0000000000..9a27d8fe62 --- /dev/null +++ b/doc/source/install/next-steps.rst @@ -0,0 +1,30 @@ +========== +Next steps +========== + +Your OpenStack environment now includes the dashboard. + +After you install and configure the dashboard, you can +complete the following tasks: + +* Provide users with a public IP address, a username, and a password + so they can access the dashboard through a web browser. In case of + any SSL certificate connection problems, point the server + IP address to a domain name, and give users access. + +* Customize your dashboard. See section + `Customize and configure the Dashboard + `__. + +* Set up session storage. See + `Set up session storage for the dashboard + `__. + +* To use the VNC client with the dashboard, the browser + must support HTML5 Canvas and HTML5 WebSockets. + + For details about browsers that support noVNC, see + `README + `__ + and `browser support + `__. diff --git a/doc/source/install/note_configuration_vary_by_distribution.txt b/doc/source/install/note_configuration_vary_by_distribution.txt new file mode 100644 index 0000000000..337c569667 --- /dev/null +++ b/doc/source/install/note_configuration_vary_by_distribution.txt @@ -0,0 +1,7 @@ +.. note:: + + Default configuration files vary by distribution. You might need + to add these sections and options rather than modifying existing + sections and options. Also, an ellipsis (``...``) in the configuration + snippets indicates potential default configuration options that you + should retain. diff --git a/doc/source/install/verify-debian.rst b/doc/source/install/verify-debian.rst new file mode 100644 index 0000000000..e067548e6d --- /dev/null +++ b/doc/source/install/verify-debian.rst @@ -0,0 +1,11 @@ +=========================== +Verify operation for Debian +=========================== + +Verify operation of the dashboard. + +Access the dashboard using a web browser at +``http://controller/``. + +Authenticate using ``admin`` or ``demo`` user +and ``default`` domain credentials. diff --git a/doc/source/install/verify-obs.rst b/doc/source/install/verify-obs.rst new file mode 100644 index 0000000000..06c35f188e --- /dev/null +++ b/doc/source/install/verify-obs.rst @@ -0,0 +1,11 @@ +======================================================= +Verify operation for openSUSE and SUSE Linux Enterprise +======================================================= + +Verify operation of the dashboard. + +Access the dashboard using a web browser at +``http://controller/``. + +Authenticate using ``admin`` or ``demo`` user +and ``default`` domain credentials. diff --git a/doc/source/install/verify-rdo.rst b/doc/source/install/verify-rdo.rst new file mode 100644 index 0000000000..9fb6721517 --- /dev/null +++ b/doc/source/install/verify-rdo.rst @@ -0,0 +1,11 @@ +======================================================== +Verify operation for Red Hat Enterprise Linux and CentOS +======================================================== + +Verify operation of the dashboard. + +Access the dashboard using a web browser at +``http://controller/dashboard``. + +Authenticate using ``admin`` or ``demo`` user +and ``default`` domain credentials. diff --git a/doc/source/install/verify-ubuntu.rst b/doc/source/install/verify-ubuntu.rst new file mode 100644 index 0000000000..c36f139f51 --- /dev/null +++ b/doc/source/install/verify-ubuntu.rst @@ -0,0 +1,11 @@ +=========================== +Verify operation for Ubuntu +=========================== + +Verify operation of the dashboard. + +Access the dashboard using a web browser at +``http://controller/horizon``. + +Authenticate using ``admin`` or ``demo`` user +and ``default`` domain credentials.