Admin Dashboard 4

Administering Admin Dashboard

Instructions on how to install and run the Sophora Advanced Administration Dashboard

Installing the Dashboard

The Administration Dashboard requires at least Java 8. The maximum supported Java version is 17, which is also recommended. It uses the default Sophora directory structure (see Configuring the Sophora Server).

To install the Dashboard,

  1. unpack the archive to a folder named "apps",
  2. create a symlink named "sophora-dashboard2" to the extracted folder inside the "apps" folder,
  3. create a folder for the instance date like "dashboard2",
  4. create a symlink to ../apps/sophora-dashboard2/dashboard.sh in that folder,
  5. create a symlink to ../apps/sophora-dashboard2/yo in that folder,
  6. create the file config/dashboard-config.json as described below.

The folder structure should look like depicted (question marks are symlinks). In case the logs and persistence folders don't exist, they will be created automatically once the Dashboard is started.

Dashboard Directory Structure
Dashboard Directory Structure (Image: subshell/CC BY)

Configuration

The Dashboard is designed to do most of its configuration automatically. However, some initial settings have to be provided and some optional ones can be added. All the configuration is done in the config/dashboard-config.json file. Below you can see an example configuration:

{
	httpPort: 8090,
	login: "dashboard",
 	password: "dashboardSecret",
	vmargs: "-Xmx512m",
	hostname: "test.subshell.com",
	defaultPollInterval: 10000,
	statusPollInterval: 1000,
	documentCountInterval: 3600000,
	server: {
		sophoraUsername: "admin",
		sophoraPassword: "secret",
		masterHostname: "trunk.subshell.com",
		masterHttpPort: 1196,
		contentApiPath: "/content-api",
		jolokiaUsername: "jolokia",
		jolokiaPassword: "secret",
		jolokiaPath: "/jolokia",
		hasEmbeddedSolr: true,
		solrUsername: "solr",
		solrPassword: "solr",
		solrPath: "/solr",
		tomcatJmx: {
			port: 9004,
			username: "",
			password: ""
		}
	},
	importer: {
		jolokiaUsername: "importerjmx",
		jolokiaPassword: "secret",
		jolokiaPath: "/jolokia"
	},
 	indexer: {
		jolokiaUsername: "admin",
		jolokiaPassword: "secret",
		jolokiaPath: "/jolokia"
	},
	mail: {
		recipients: [
			"recipient1@subshell.com",
			"recipient2@subshell.com"
		],
		smtpHost: "localhost",
		smtpPort: 25,
		username: "user",
		password: "secret",
		fromAddress: "sophora-dashboard@yourdomain.com",
		notificationDelay: 30
	},
	links: [ 		
		{ 	url: "http://www.subshell.com/de/index.html", 		 
			description: "Subshell" 
		}, 		
		{ 	url: "https://github.com/airbnb/javascript", 		 
			description: "JavaScript Style Guide" 		
		}
	]
}

The following list explains the configuration options:

Configuration Options
KeyExplanationExampleValue typeRequiredDefault
httpPortThe port at which the Dashboard will be reachable.8090Integerno8080
loginThe login username for the Dashboard Basic Authentication. If omitted, no credentials are required for access."dashboard"Stringno""
passwordThe login password for the Dashboard Basic Authentication. If omitted, no credentials are required for access."dashboardPassword"Stringno""
vmargsThe arguments that should be passed to the Java VM."-Xmx512m"Stringno""
hostnameHostname of the Dashboard server. Use this if the automatic resolution of the hostname fails or the external host to reach the dashboard is different."test.subshell.com"Stringnodetermined by operating system
defaultPollIntervalThe Interval in which the Dashboard polls most of the values it aggregates from other components in milliseconds. Minimal value is 1000.20000Integerno10000
statusPollIntervalThe interval in which the Dashboard polls status (online/offline) information from other components in milliseconds. The minimal value is 100.2500Integerno1000
documentCountIntervalThe interval in which the Dashboard counts the documents on all the cluster nodes and Sophora Staging Server in milliseconds. This is a very expensive operation, hence intervals smaller than 5 minutes (300000) are strongly discouraged.7200000Integerno3600000
serverA block of configuration applied to the handling of all Sophora Servers in the cluster. See the corresponding table below for all available options.JSON Objectyes
importerA block of configuration applied to the handling of all Sophora Importers in the cluster. See the corresponding table below for all available options.JSON Objectyes
indexerA block of configuration applied to the handling of all Sophora Indexers in the cluster. See the corresponding table below for all available options.JSON Objectyes
mailA block of configuration used to send email notifications. See the corresponding table below for all available options. If no mail block exists, the Dashboard does not send emails.JSON Objectno
linksA collection of configurable links that will be visible in a menu inside the dashboard's navigation bar. Each link is a JSON Object, that must consist of an url and a description. The latter will be used as the link name shown in the menu.JSON Arrayno
ibfEnabledActivates support for checking document counts efficiently using invertible bloom filters. Set this to true if you have activated the configuration option sophora.ibf.enabled in the sophora.properties of all Sophora Servers monitored by this Dashboard instance.trueBooleannofalse
Server Block
KeyExplanationExampleValue typeRequiredDefault
sophoraUsernameThe username that is used to poll values from the Content API."admin"Stringyes-
sophoraPasswordThe password that is used to poll values from the Content API."secret"Stringyes-
masterHostnameThe hostname of the Sophora Primary (Master) Server."sophora.example.com"Stringyes-
masterHttpPortThe HTTP port of the Sophora Primary (Master) Server.1196Integeryes-
masterHttpUseSslSet to true if the Sophora Primary (Master) connection uses https.trueBooleannofalse
contentApiPathThe part of the Content API URL after the port."/content-api"Stringno"/content-api"
jolokiaUsernameThe username for the Jolokia service."jolokia"Stringno"jolokia"
jolokiaPasswordThe password for the Jolokia service."jolokia"Stringno"jolokia"
jolokiaPathThe part of the Jolokia URL after the port."/jolokia"Stringno"/jolokia"
hasEmbeddedSolrSet to true if the Sophora Server uses an embedded Solr which should be requested.trueBooleannotrue
solrUsernameThe username for the Solr service."solr"Stringno"solr"
solrPasswordThe password for the Solr service."solr"Stringno"solr"
solrPathThe part of the Solr URL after the port."/solr"Stringno"/solr"
tomcatJmxA block of configuration to access the JMX of any Tomcat server connected to the Sophora system.see rows belowJSON Objectnosee rows below
tomcatJmx > portThe port of the JMX service of the Tomcats (all Tomcats need to offer JMX on the same port).9004Integerno9004
tomcatJmx > usernameThe username used to access the JMX service of the Tomcats (all Tomcats need to be configured alike)."jmx-user"Stringno""
tomcatJmx > passwordThe password used to access the JMX service of the Tomcats (all Tomcats need to be configured alike)."password"Stringno""
Importer Block and Indexer Block
KeyExplanationExampleValue typeRequiredDefault
jolokiaUsernameThe username for the Jolokia service."jolokia"Stringno"jolokia"
jolokiaPasswordThe password for the Jolokia service."jolokia"Stringno"jolokia"
jolokiaPathThe part of the Jolokia URL after the port."/jolokia"Stringno"/jolokia"
Mail Block
KeyExplanationExampleValue typeRequiredDefault
recipientsA list of mail addresses that will be notified in case of problems detected by the Dashboard.["recipient1@example.com", "recipient2@example.com"]JSON Array of Stringsyes-
smtpHostThe hostname for the SMTP server used."smtp.example.com"Stringno"localhost"
smtpPortThe port for the SMTP server used.25Integerno25
userThe username used to login to the SMTP service."mail-user"Stringno-
passwordThe password used to login to the SMTP service."secret"Stringno-
fromAddressThe address used for the FROM field in sent e-mails."sophora-dashboard@yourdomain.com"Stringnodetermined automatically
notificationDelayThe delay before a notification mail is sent in case of a problem in seconds. No notification will be sent if the problem is fixed within the delay.60Integerno30

Ports

The following ports are in use for the communication between the Dashboard and Sophora’s components:

Dashboard – Sophora Primary (Master), Staging Server

  • HTTP-port of the server. Also, the communication of the DeskClient, the Content API and Solr run on this port.
  • Set masterHttpUseSsl to true if the server uses HTTPS.

Dashboard – Importer

  • Jolokia-port. Configurable via the option sophora.importer.jolokia.port in sophora-importer.properties. 1496 is set as the default.

Dashboard – Tomcats

  • JMX-port of the Tomcat. 9004 is set as the default in the DeskClient.

JMX in Tomcat

The Dashboard uses the JMX-URLs as follows:

service:jmx:rmi:///jndi/rmi://<HOSTNAME>:<PORT>/jmxrmi

The port and the authentication can be configured via dashboard-config.json.

In order to allow access through firewall and VPN tunnels you can configure the JmxRemoteLifecycleListener. For more information see JMX Remote Lifecycle Listener.

Web Application Configuration

Webapps/deliveries only appear in the Dashboard, if sophora.delivery.externalUrl is configured (since Delivery 2.1.16, 2.2.6 and 2.3.0). The configured URL need to point at the Tomcat context of the webapp and need to be accessible by the Dashboard.

More about configuration parameters.

Starting and Stopping the Dashboard Application

To start the Dashboard, use the start and stop script dashboard.sh that comes with the installation. In a console in the directory of the script, type ./dashboard.sh start or ./dashboard.sh stop.

Using HTTP Proxies

If the Dashboard is required to use a HTTP proxy to connect to Sophora Servers, the JVM system properties http.proxyHost and http.proxyPort may be used. You can use the vmargs configuration property of the Dashboard in config/dashboard-config.json, for example:

{
  ...
  vmargs: "-Dhttp.proxyHost=10.0.0.1 -Dhttp.proxyPort=8080",
  ...
}

Troubleshooting

The Dashboard persists tools and servers it was once connected to in the /persistence folder. It can help to stop the Dashboard remove the contents of this folder and start the Dashboard again. Only remove the contents of this folder if the Dashboard is not running.

Last modified on 10/16/20

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.

Icon