Hue High Availability

This page explains how to configure Hue for high availability with Cloudera Manager and at the command line. It assumes that you have the Hue service installed and one or more Hue server roles defined. If not, see Adding a Hue Service and Role Instance.

Configuring a Cluster for Hue High Availability Using Cloudera Manager

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

In Cloudera Manager, you can configure your Hue cluster for high availability by adding a Hue load balancer and multiple Hue servers.


Configuring Hue for High Availability in Cloudera Manager

  1. Go to the Hue service.
  2. Select the Hue Instances tab.
  3. Add one or more Hue servers to an existing Hue server role. At least two Hue server roles are required for high availability:
    1. Click Add Role Instances.
    2. Click Select hosts under Hue Server (HS).
    3. Check the box for each host on which you want a Hue server (which adds HS icons).
    4. Click OK.
  4. Add one load balancer:
    1. Click Select hosts under Load Balancer (LB).
    2. Check the box for the host on which you want the load balancer (which adds an LB icon).
    3. Click OK.
  5. Click Continue.
  6. Select the Configuration tab and filter on Scope > Hue Server and Category > Security.
  7. Find the property, Enable TLS/SSL for Hue, and check the box by Hue Server Default Group.
  8. Clear Scope and Category filters and review other options to ensure they meet your needs. Some to consider are:
    • Hue Load Balancer Port - The Apache Load Balancer listens on this port. The default is 8889.
    • Path to TLS/SSL Certificate File - The TLS/SSL certificate file.
    • Path to TLS/SSL Private Key File - The TLS/SSL private key file.
  9. Save any configuration changes.
  10. Start the load balancer and new Hue servers:
    1. Check the box by each new role type.
    2. Select Actions for Selected > Start.
    3. Click Start and Close.

For more information, see Automatic High Availability and Load Balancing of Hue.

Configuring a Cluster for Hue High Availability Using the Command Line

This section applies to unmanaged deployments without Cloudera Manager. It explains how to install and configure nginx from the command line. To make the Hue service highly available, configure at least two instances of the Hue service, each on a different host. Also configure the nginx load balancer to direct traffic to an alternate host if the primary host becomes unavailable. For advanced configurations, see the nginx documentation.


  • The Hue service is installed and two or more Hue server roles are configured.
  • You have network access through SSH to the host machines with the Hue server role(s).
  • An external database was added each Hue server is configured to use it. See Using an External Database for Hue Using Cloudera Manager.

Installing and Configuring the nginx Load Balancer

To enable high availability for Hue, install the nginx load balancer on one of the Hue instances. Clients access this instance through a designated port number, and the nginx load balancer directs the request to one of the Hue server instances.

  1. With SSH, log in as the root user to the host machine of one of the Hue instances.
  2. Install nginx:
    Red Hat/Centos:
    yum install nginx
    apt-get install nginx
  3. Create the following Hue cluster configuration file:
  4. Configure hue.conf with the following template:
    server {
        server_name NGINX_HOSTNAME;
        charset utf-8;
        listen 8001;
        # Or if running hue on https://
        ## listen 8001 ssl;
        ## ssl_certificate /path/to/ssl/cert;
        ## ssl_certificate_key /path/to/ssl/key;
        client_max_body_size 0;
        location / {
            proxy_pass http://hue;
            proxy_set_header Host $http_host;
            proxy_set_header X-Forwarded-For $remote_addr;
            # Or if the upstream Hue instances are running behind https://
            ## proxy_pass https://hue;
        location /static/ {
            # Uncomment to expose the static file directories.
            ## autoindex on;
            # If Hue was installed with packaging install:
            ## alias /usr/lib/hue/build/static/;
            # Or if on a parcel install:
            alias /opt/cloudera/parcels/CDH/lib/hue/build/static/;
            expires 30d;
            add_header Cache-Control public;
    upstream hue {
        # List all the Hue instances here for high availability.
        server HUE_HOST1:8888 max_fails=3;
        server HUE_HOST2:8888 max_fails=3;
  5. Update the following in the hue.conf file:
    • Replace NGINX_HOSTNAME with the URL of the host where you installed nginx. For example:
    • In the location/static block, comment or uncomment the alias lines, depending on whether your cluster was installed using parcels or packages. (The comment indicator is #.)
    • In the upstream hue block, list all the hostnames, including port number, of the Hue instances in your cluster. For example:
      server max_fails=3;
      server max_fails=3;
      server max_fails=3;
    • If the Hue service in your cluster is configured to use TLS/SSL:
      • Uncomment these lines, and replace the path names with the paths for your cluster:
        ## listen 8001 ssl;
        ## ssl_certificate /path/to/ssl/cert;
        ## ssl_certificate_key /path/to/ssl/key;
      • Uncomment the following line in the location / block:
        ## proxy_pass https://hue;
        and comment out the following line:
        proxy_pass http://hue;
      • Comment out the following line:
        listen 8001
  6. Start nginx:
    sudo service nginx start
  7. Test your installation by opening the Hue application in a web browser, using the following URL:
    • Without TLS/SSL: http://NGINX_HOSTNAME:8001

    • With TLS/SSL: https://NGINX_HOSTNAME:8001

    NGINX_HOSTNAME is the name of the host machine where you installed nginx.

  8. Test high availability:
    1. Stop the Hue service instance on the host where you installed nginx.
    2. Access the Hue application as described in the previous step. If you can connect to the Hue application, you have successfully enabled high availability.
  9. If necessary, configure your backend database for high availability. Consult the vendor documentation for the database that you configured for Hue.