Deploying Web Console

Overview

In some scenarios, containerized deployment using Docker might not be available or desirable. For example, some organizations may prefer to manage deployment using virtual or cloud machine images (e.g., .vmx or .ami images) or to deploy on bare metal. To meet such infrastructure policies, you can deploy GridGain Web Console directly on the host operating system using a pre-built ZIP package.

Navigate to the GridGain Downloads page to obtain the package.

The Web Console ZIP distributable package contains all of the components of the Web Console runtime environment, including:

The Web Console front-end
The Web Console backend used to store user data like configuration and monitoring telemetry information
The Web Console user agent (or simply Web Agent), a Java-based process used to proxy connections between the Web Console and the GridGain cluster being monitored (note that if you intend to monitor more than one GridGain cluster, you’ll need to run more than one agent, as described here)

Provisioning

While the various Web Console processes can be run on the same physical or virtual host as a GridGain cluster node, GridGain recommends provisioning a physical or virtual server separate from the cluster being monitored and running the various Web Console processes there.

Requirements

JDK 8 or JDK 11
Supported browsers: Chrome, Firefox, Safari, Edge.
The GridGain cluster should be started with the ignite-rest-http module in the classpath. To do this: copy the ignite-rest-http folder from {gridgain_dir}\libs\optional\ to {gridgain_dir}\libs\.

Running Web Console

Unpack/extract gridgain-web-console-YYYY.MM.PP.zip.
Change to the folder where Web Console was unpacked.
Start the web-console.{bat|sh} executable for your platform:
$ ./web-console.sh
$ web-console.bat
Open localhost:8008 in a browser.
Sign in (or create a new user).
Download the Web Console agent. A download link is available at the bottom of the left-hand navigation bar.
Launch the Web Agent from the gridgain-web-console-agent-x.x.x folder.

By default, the Web Console control process will listen for incoming connections on port 8008.

Technical details

Package content:
- libs - this folder contains Web Console dependencies.
- work - this folder contains all Web Console data (registered users, created objects, …) and should be preserved in case of update to new version.
- agent_dists - this folder contains Web Agent.
Web console will start on default HTTP port 8008 and bind to all interfaces: 0.0.0.0.

Running the Web Agent

The Web Agent process that proxies connections between the Web Console and the target GridGain cluster is not started automatically by the Web Console control process. Instead, you must start it separately and you must start a separate Web Agent instance for each cluster you wish to monitor. A complete Web Agent runtime is provided with the Web Console ZIP distributable in the agent-dists/ subdirectory of the unzipped package. You can run the Web Agent with its default configuration by simply executing the gridgain-web-console-agent.{sh|bat} script inside this subdirectory. However, you’ll likely need to configure your Web Agent instance to point at unique URIs for your cluster and Web Console instances. Information about this configuration is available here: gridgain-web-console-agent-x.x.x\README.txt.

Configuration

You can use application.properties files, YAML files, and environment variables to manage Web Console configuration.

Properties are considered in the following order:

OS environment variables.
Properties in the /config subdirectory of the working directory or in the working directory (application.properties and YAML variants).

The YAML format description can be found here.

Various properties can be specified inside your application.properties file or inside your application.yml file.

This appendix provides a list of common Spring Boot properties and references to the underlying classes that consume them:

# Sign up configuration.
account.signup.enabled=true # Enable self registration
account.activation.enabled=false # Enable account activation
account.activation.timeout=1800000 # Activation timeout(milliseconds)
account.activation.sendTimeout=180000 # Activation send email throttle (milliseconds)

# Embedded server configuration.
server.address=0.0.0.0 # Network address to which the Web Console should bind.
server.port=8008 # Web Console HTTP port.

# Email (MailProperties)
spring.mail.default-encoding=UTF-8 # Default MimeMessage encoding.
spring.mail.host= # SMTP server host. For instance, `smtp.example.com`.
spring.mail.jndi-name= # Session JNDI name. When set, takes precedence over other Session settings.
spring.mail.password= # Login password of the SMTP server.
spring.mail.port= # SMTP server port.
spring.mail.properties.*= # Additional JavaMail Session properties.
spring.mail.protocol=smtp # Protocol used by the SMTP server.
spring.mail.test-connection=false # Whether to test that the mail server is available on startup.
spring.mail.username= # Login user of the SMTP server.
spring.mail.web-console-url= # Web console url for links in notifications.

# SSL options.
server.ssl.ciphers= # Supported SSL ciphers.
server.ssl.client-auth= # Client authentication mode.
server.ssl.enabled=true # Whether to enable SSL support.
server.ssl.enabled-protocols= # Enabled SSL protocols.
server.ssl.key-alias= # Alias that identifies the key in the key store.
server.ssl.key-password= # Password used to access the key in the key store.
server.ssl.key-store= # Path to the key store that holds the SSL certificate (typically a jks file).
server.ssl.key-store-password= # Password used to access the key store.
server.ssl.key-store-provider= # Provider for the key store.
server.ssl.key-store-type= # Type of the key store.
server.ssl.protocol=TLS # SSL protocol to use.
server.ssl.trust-store= # Trust store that holds SSL certificates.
server.ssl.trust-store-password= # Password used to access the trust store.
server.ssl.trust-store-provider= # Provider for the trust store.
server.ssl.trust-store-type= # Type of the trust store.

Example: Mail Setup

Example properties for a Gmail SMTP Server:

spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=<login user to smtp server>
spring.mail.password=<login password to smtp server>
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

Example: HTTPS Setup (with a Self-Signed Certificate) Between Web Agent and Web Console

Generate a self-signed certificate.
Configure Web Console to use SSL port: 443 and key-store with generated certificate.
Configure Web Agent to use same certificate (use options "-sks path-to-key-store -sksp key-store-password" OR set server-key-store and server-key-store-password in default.properties).

Example properties for Web Console:

server.port=443
server.ssl.key-store-type=JKS
server.ssl.key-store=certificates/server.jks
server.ssl.key-store-password=change_me

Example: HTTPS setup (with a Self-Signed Certificate) Between Web Agent and Cluster

Generate self-signed certificate and trust store.
Prepare configuration for Jetty web server with HTTPS support.
Prepare configuration for cluster that will refer to Jetty configuration from step 2.
Start Web Agent with the -Dtrust.all=true option (because of self-signed certificate).

Create the following Jetty configuration to enable ssl/tls connection (more detail about Jetty configuration can be found here):

<?xml version="1.0"?>

<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">

<Configure id="Server" class="org.eclipse.jetty.server.Server">
    <Arg name="threadPool">
        <!-- Default queued blocking thread pool -->
        <New class="org.eclipse.jetty.util.thread.QueuedThreadPool">
            <Set name="minThreads">10</Set>
            <Set name="maxThreads">200</Set>
        </New>
    </Arg>

    <New id="httpsCfg" class="org.eclipse.jetty.server.HttpConfiguration">
        <Set name="secureScheme">https</Set>
        <Set name="securePort"><SystemProperty name="IGNITE_JETTY_PORT" default="8443"/></Set>
        <Set name="sendServerVersion">true</Set>
        <Set name="sendDateHeader">true</Set>
        <Call name="addCustomizer">
            <Arg><New class="org.eclipse.jetty.server.SecureRequestCustomizer"/></Arg>
        </Call>
    </New>

    <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
        <Set name="keyStorePath">/opt/keystore/server.jks</Set>
        <Set name="keyStorePassword">123456</Set>
        <Set name="keyManagerPassword">123456</Set>
        <Set name="trustStorePath">/opt/keystore/trust.jks</Set>
        <Set name="trustStorePassword">123456</Set>
    </New>

    <Call name="addConnector">
        <Arg>
            <New class="org.eclipse.jetty.server.ServerConnector">
                <Arg><Ref refid="Server"/></Arg>
                <Arg>
                    <Array type="org.eclipse.jetty.server.ConnectionFactory">
                        <Item>
                            <New class="org.eclipse.jetty.server.SslConnectionFactory">
                                <Arg><Ref refid="sslContextFactory"/></Arg>
                                <Arg>http/1.1</Arg>
                            </New>
                        </Item>
                        <Item>
                            <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                                <Arg><Ref refid="httpsCfg"/></Arg>
                            </New>
                        </Item>
                    </Array>
                </Arg>
                <!--
                    Note that in order to override local host and port values,
                    system properties must have names IGNITE_JETTY_HOST and
                    IGNITE_JETTY_PORT accordingly.
                -->
                <Set name="host"><SystemProperty name="IGNITE_JETTY_HOST" default="0.0.0.0"/></Set>
                <Set name="port"><SystemProperty name="IGNITE_JETTY_PORT" default="8443"/></Set>
                <Set name="idleTimeout">30000</Set>
                <Set name="reuseAddress">true</Set>
            </New>
        </Arg>
    </Call>

    <Set name="handler">
        <New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection">
            <Set name="handlers">
                <Array type="org.eclipse.jetty.server.Handler">
                    <Item>
                        <New id="Contexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
                    </Item>
                </Array>
            </Set>
        </New>
    </Set>

    <Set name="stopAtShutdown">false</Set>
</Configure>

The path to this configuration should be passed to the ConnectorConfiguration.setJettyPath(String) property in the node configuration.

The path to the Jetty configuration file should be either absolute, or relative to IGNITE_HOME. (more details about REST HTTP configuration can be found here).

Jetty configuration and node configuration should be identical on all nodes.

If Jetty configuration is not provided for some nodes then GridGain will start the Jetty server with a simple HTTP connector.

Example grid configuration:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

    <import resource="common.xml"/>

    <bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
        <!-- Enable SSL for REST HTTP -->
        <property name="connectorConfiguration">
            <bean class="org.apache.ignite.configuration.ConnectorConfiguration">
                <property name="jettyPath" value="<path to rest-jetty-ssl.xml>"/>
            </bean>
        </property>
    </bean>
</beans>

Troubleshooting and Useful Information

If you get a "Forbidden" error in your browser, check that all the security policies are properly set in your operating system.
The logs can be found in the <install_dir>/work/logs/ folder.

© 2024 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Jan 26, 2024