Installation on SUSE Linux Enterprise Server (SLES) 15 / openSUSE Leap 15.0¶
The installation of the Business Bot Platform on SUSE Linux Enterprise
Server (SLES) 15 / openSUSE Leap 15.0 is supported by an installer
(installation wizard). The software is provided as an rpm package (file name:
bbp-<edition>-<release>-<fixpack>-1-0.<architecture>.rpm
). After starting the installation, the installer checks
various system requirements (e.g. available disk space) as well as
compatibility with the operating system.
System Configuration¶
The following installation and configuration uses demo.bbp.local
as system hostname. If you want to use a different hostname, you will need to modify configuration files and commands for your environment. Ensure that this hostname / domain is also available in your network (not only on your local system).
Installation of the Business Bot Platform¶
The installer creates a new user during the installation. The user bbp
runs Tomcat. All files are copied to
the directory /opt/bbp
. The following steps will guide you through the installation.
Download the rpm package from the Service Portal.
The installation of the package is done with the rpm command:
1 | $ sudo rpm -ivh bbp-community-r2019-ga-1-0.x86_64.rpm
|
Subsequently, the POST installation script must be executed to complete the installation and configure the components of the Business Bot Platform. Therefore, run following command:
1 | $ /opt/bbp/scripts/postInstall.sh
|
You should receive the following output:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | $ /opt/bbp/scripts/postInstall.sh --------------------------------------------- Copyright(c) 2016-2020 Citunius GmbH BBP Post install started at 2020-11-26_00-21-37 --------------------------------------------- [OK] Diskspace check passed Running on OS: SuSE Check required packages ... > [OK] Package httpd is already installed. > [OK] Package mariadb is already installed. Prepare Apps ... Configure Tomcat ... Enable the Tomcat service, so it starts on server boot ... Configure Firewall ... success success success success success Deploy WebApp BBP ... Start the Tomcat Service ... Post installation action of the Business Bot Platform has finished. In the next step, you have to configure the platform using the WebInstaller. Once you have finished this, you can access the web frontend via browser. -------------------------------------------------------------------------- Web Interface: https://demo.bbp.local:55550/bbp/admin/login -------------------------------------------------------------------------- |
Apache Webserver¶
The Apache HTTP server is the most widely-used web server in the world. It provides many powerful features including dynamically loadable modules, robust media support, and extensive integration with other popular software.
Apache serves the Business Bot platform as a reverse proxy. A reverse proxy is a kind of proxy server that accepts HTTP(S) requests and distributes them transparently to one (or more) backend server (Tomcat).
In this section, you will install and configure an Apache web server on your system.
Installation¶
Apache is available within default software repositories, which means you can install it with the yum
package manager.
To install Apache and SSL on your system, use the following command:
1 2 | $ sudo yum -y install httpd $ sudo yum install -y mod_ssl |
The system should download and install the Apache software packages.
To activate Apache, start its service first.
1 | $ sudo systemctl start httpd
|
Next, set the Apache service to start when the system boots:
1 | $ sudo systemctl enable httpd |
Finally, display information about Apache, and verify it’s currently running with:
1 | $ sudo systemctl status httpd
|
Configuration¶
- Copy the configuration file
/opt/bbp/installData/httpd/conf.d/demo.bbp.local.conf
to/etc/httpd/conf.d/demo.bbp.local.conf
.
The configuration requires an SSL certificate issued by a certification authority. You can also create a self-signed certificate or use the certificate from /opt/bbp/installData/httpd/conf/
for demonstration only. If you want to use the demo certificate, copy the files /opt/bbp/installData/httpd/conf/server.crt
(SSLCertificateFile) and /opt/bbp/installData/httpd/conf/server.key
(SSLCertificateKeyFile) to /etc/httpd/conf/
.
- Change the following parameters in the configuration file
/etc/httpd/conf/httpd.conf
:
1 2 3 4 5 | ServerName localhost:55580 # Listen 80 Listen 0.0.0.0:55580 Listen [::0]:55580 |
- Now activate the following Apache modules (if not already active) in the configuration files located in directory
/etc/httpd/conf.modules.d
:
1 2 3 4 5 6 7 8 9 | LoadModule access_compat_module modules/mod_access_compat.so LoadModule headers_module modules/mod_headers.so LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_ajp_module modules/mod_proxy_ajp.so LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so LoadModule rewrite_module modules/mod_rewrite.so LoadModule vhost_alias_module modules/mod_vhost_alias.so LoadModule ssl_module modules/mod_ssl.so |
Alternatively you can copy the module file /opt/bbp/installData/httpd/conf.modules.d/00-bbp.conf
to /etc/httpd/conf.modules.d/
. Note that Apache will issue warnings if modules are already enabled.
- Now check the Apache configuration for errors:
1 | $ apachectl configtest
|
- Finally restart the Apache web server
1 | $ systemctl restart httpd
|
Once the installation is complete, the Apache web server will be available at https://demo.bbp.local:55550/bbp/admin/login
.
Apache OOTB SSL configuration file already exists
The Apache web server already delivers a predefined SSL configuration. You can easily rename the SSL configuration file (mv /etc/httpd/conf.d/ssl.conf /etc/httpd/conf.d/ssl.conf.ootb
).
Database mariaDB¶
MariaDB is an open source database management system that is often installed as part of the popular LAMP stack. It uses a relational database and SQL (Structured Query Language) to manage its data. In this section, we will explain how to install the latest version of MariaDB on openSUSE Leap 15.0.
Installation¶
We use Yum to install the MariaDB package and press
y
to confirm that we want to continue:
1 | $ sudo zypper in mariadb mariadb-tools
|
The package mariadb-tools is necessary for the administration. Once the installation is complete, we start the daemon with the following command:
1 | $ sudo systemctl start mysql
|
systemctl
does not display the result of
all service management commands, so we use the following command to make sure we were successful:
1 | $ sudo systemctl status mysql
|
If MariaDB was started successfully, the output should contain
Active: active (running)
. Next, we want to ensure that MariaDB starts at boot, using the systemctl enable
command, which will create the necessary symlinks.
1 | $ sudo systemctl enable mysql |
Next, we will turn to securing our installation.
Securing the MariaDB Server¶
MariaDB includes a security script to change some of the less secure default options for things like remote root logins and sample users. Use this command to run the security script:
1 | $ sudo mysql_secure_installation
|
The script provides a detailed explanation for every step. The first
prompts asks for the root password, which hasn't been set so we'll
press ENTER
as it recommends. Next,
we'll be prompted to set that root password, which we'll do.
Then, we'll accept all the security suggestions by pressing
Y
and then ENTER
for the remaining prompts, which will remove anonymous
users, disallow remote root login, remove the test database, and reload the privilege tables.
Finally, now that we've secured the installation, we'll verify it's working.
Testing the Installation¶
We can verify our installation and get information about it by
connecting with the mysqladmin
tool, a
client that lets you run administrative commands. Use the following
command to connect to MariaDB as root (-u root
), prompt for a password (-p
), and return the version.
1 | $ mysqladmin -u root -p version
|
You should receive an output similar to this one:
1 2 3 4 5 6 7 8 9 10 11 12 | $ mysqladmin -u root -p version Enter password: mysqladmin Ver 9.0 Distrib 5.5.60-MariaDB, for Linux on x86_64 Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. Server version 5.5.60-MariaDB Protocol version 10 Connection Localhost via UNIX socket UNIX socket /var/lib/mysql/mysql.sock Uptime: 17 min 40 sec Threads: 1 Questions: 25 Slow queries: 0 Opens: 1 Flush tables: 2 Open tables: 27 Queries per second avg: 0.023 |
This indicates that the installation was successful.
In the next step it is necessary to setup the Business Bot Platform. Therefore, follow chapter Web-Setup of the platform .
Create new Database¶
Notice
You have only to create an empty database, since the database is imported via the Web setup.
The Business Bot platform manages all data such as mobile users, chatbots and settings in one database. Therefore it is necessary to create the database for the platform in mariaDB. To do this, execute the following commands:
Create a new database with the name bbp
1 | $ mysql -u root -p -e "create database bbp DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" |
The database creation is now complete.
Optional: Configuring the Database Settings of the Business Bot Platform¶
Notice
This step is optional, since the database settings are made via the Web setup.
If you want to change the data resource of the Business Bot platform, you can do that as follows:
1 | $ vi /opt/bbp/apps/tomcat/webapps/bbp/WEB-INF/classes/META-INF/persistence.xml
|
After the configuration of the Business Bot platform is complete, you need to restart Tomcat:
1 | $ sudo systemctl restart tomcat
|
The next step is to register the Business Bot platform. Therefore, follow the instructions in chapter Installing a license .
Troubleshooting¶
Apache web server cannot be started: Failed to configure certificate¶
Problem: Apache web server does not start
Check the log file /var/log/demo.bbp.local.error.log
for the following error:
1 | Failed to configure certificate demo.bbp.local:443:0 (with chain), check /etc/httpd/conf/server.crt / SSL Library Error: error:140AB18F:SSL routines:SSL_CTX_use_certificate:ee key too small
|
Solution:
The SSL key is not long enough and is therefore a potential security risk. Create a new SSL certificate with a length of at least 2028 bits
(openssl req -x509 -nodes -days 999 -newkey rsa:2048 -keyout /etc/httpd/conf/server.key -out /etc/httpd/conf/server.crt
).
Tomcat does not start: Protocol handler start failed¶
Problem: Tomcat does not start and the following error is logged in the log:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | 26-Nov-2020 20:44:02.383 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-55590"] 26-Nov-2020 20:44:02.390 SEVERE [main] org.apache.catalina.util.LifecycleBase.handleSubClassException Failed to start component [Connector[AJP/1.3-55511]] org.apache.catalina.LifecycleException: Protocol handler start failed at org.apache.catalina.connector.Connector.startInternal(Connector.java:1038) at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:183) at org.apache.catalina.core.StandardService.startInternal(StandardService.java:438) at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:183) at org.apache.catalina.core.StandardServer.startInternal(StandardServer.java:930) at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:183) at org.apache.catalina.startup.Catalina.start(Catalina.java:633) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:343) at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:474) Caused by: java.lang.IllegalArgumentException: The AJP Connector is configured with secretRequired="true" but the secret attribute is either null or "". This combination is not valid. at org.apache.coyote.ajp.AbstractAjpProtocol.start(AbstractAjpProtocol.java:264) at org.apache.catalina.connector.Connector.startInternal(Connector.java:1035) ... 12 more |
Solution:
-
Check in file
demo.bbp.local.conf
that attributesecret="secret"
is set forProxyPass
. Example:ProxyPass /bbp http://localhost:55590/bbp retry=0 secret="secret"
-
Check in file
server.xml
that attributesecret="secret" secretRequired="true"
is set forConnector
. Example:<Connector port="55511" protocol="AJP/1.3" redirectPort="55543" secret="secret" secretRequired="true"/>
Tomcat does not start: SELinux is preventing ..¶
Problem:
Tomcat does not start and the following error is logged in the log /var/log/messages
:
1 | SELinux is preventing /usr/sbin/httpd from name_connect access on the tcp_socket port 55590
|
Solution:
If you want to allow HTTPD scripts and modules to connect to databases over the network.
Then you must inform SELinux about this by enabling the boolean httpd_can_network_connect_db
.
You can read the mysqld_selinux
man page for more details.
Run the following commands to fix this issue:
1 2 | setsebool -P httpd_can_network_connect_db 1 setsebool -P nis_enabled 1 |