WebService Installation

1. Download the Packages

This guide will assist you with installing CleanSpeak WebService on your server (Linux, macOS, or Windows) and works equally well for development environments.

Log into the CleanSpeak website at https://account.cleanspeak.com/account/, navigate to the Licenses section, and click on Download CleanSpeak. You will need to download one of the CleanSpeak WebService package that matches the operating system you will be installing CleanSpeak on.

2. Red Hat

Use the RPM bundle to install on a Red Hat system (including Fedora and CentOS). Execute this command to install the CleanSpeak WebService RPM (replace with the correct <version> number):

$ sudo rpm -i cleanspeak-webservice-<version>.rpm

3. Debian

Use the DEB bundle to install on a Debian system (including Ubuntu, Mint, and Debian base). Execute this command to install the CleanSpeak WebService DEB (replace with the correct <version> number):

$ sudo dpkg -i cleanspeak-webservice-<version>.deb

4. macOS

To install on macOS, use the ZIP bundle. Extract the CleanSpeak WebService ZIP file anywhere on the file system. Remember where you extract the file. This location will be referred to as CLEANSPEAK_HOME. We suggest extracting this file to a directory like /usr/local/cleanspeak.

Once the zip bundle has been extracted, the directory structure should look similar. Your directory structure would be different if you installed it somewhere other than the default CLEANSPEAK_HOME. This is only for shown as an example.

/usr/local/cleanspeak/config
/usr/local/cleanspeak/config/keystore
/usr/local/cleanspeak/config/cleanspeak.properties
/usr/local/cleanspeak/cleanspeak-webservice

5. Windows

To install on Windows use the ZIP bundle. Extract the CleanSpeak WebService ZIP file anywhere on the file system. Remember where you extract the file. This location will be referred to as CLEANSPEAK_HOME. We suggest extracting this file to a directory such as C:\cleanspeak on Windows.

Once the zip bundle has been extracted, the directory structure should look similar to this. If you installed somewhere other the default CLEANSPEAK_HOME, your directory structure will be different, this is only for shown as an example.

C:\cleanspeak\configS
C:\cleanspeak\config\keystore
C:\cleanspeak\config\cleanspeak.properties
C:\cleanspeak\cleanspeak-webservice\

Next, install the Windows service by changing to the directory you installed CleanSpeak (i.e. C:\cleanspeak\cleanspeak-webservice\apache-tomcat\bin) and then running the install command. Here are those two steps:

C:\>cd C:\cleanspeak\cleanspeak-webservice\apache-tomcat\bin
C:\cleanspeak\cleanspeak-webservice\apache-tomcat\bin>CleanSpeakWebService.exe /install

6. Service Name

As long as your installation method installed CleanSpeak WebService as a service, the service name will be as follows:

You can use the operating system commands to start, stop and check the status of CleanSpeak using this service name.

7. Start CleanSpeak WebService

Next, you need to start CleanSpeak WebService so that you can enter Maintenance Mode and allow CleanSpeak to create the database. Use the instructions below to start CleanSpeak based on the platform you installed it on. Also note that the CLEANSPEAK_HOME directory is the location you installed CleanSpeak WebService to.

$ sudo service cleanspeak-webservice start

$ <CLEANSPEAK_HOME>/cleanspeak-webservice/apache-tomcat/bin/startup.sh

C:\cleanspeak\cleanspeak-webservice\apache-tomcat\bin>startup.bat

C:\> net start CleanSpeakWebService

8. Maintenance Mode

You will access CleanSpeak WebService’s Maintenance Mode setup via the browser. If you installed CleanSpeak WebService on your local machine, you’ll access this interface by opening http://localhost:8011 in your browser. If CleanSpeak is running on a remote server, change the server name in the URL to match your server’s name.

The first step of Maintenance Mode will prompt you to enter your license Id. You can retrieve your license Id from the CleanSpeak website by logging into your account here: https://account.cleanspeak.com/account/

You should see a screen that looks like this:

Your license Id will be written out to the CleanSpeak configuration file in case you need to change it in the future.

In the next step of Maintenance Mode you will see a screen like this:

You will need to confirm the database server name, port, database type and database name are all correct. Below these fields are the super user username and password credentials. You need to supply CleanSpeak with the username and password for a database user that has access to create new databases and schemas. Below this section are the username and password that CleanSpeak will use to connect to the database. You should ensure that all of these fields are correct and then hit the submit button.

After you hit submit, you should see a screen that indicates that CleanSpeak WebService is starting. After this screen disappears, CleanSpeak WebService will be fully installed, configured and running.

9. Advanced Installation

These instructions will assist you in editing the CleanSpeak WebService configuration file and installing the database schema via the command-line. If you used Maintenance Mode to configure CleanSpeak WebService, you can skip this section.

# Create the cleanspeak database, replace <root_user> a valid superuser.
mysql --default-character-set=utf8 -u<root_user> -e "create database cleanspeak character set = 'utf8mb4' collate = 'utf8mb4_bin';"

# Grant cleanspeak all authority to cleanspeak database, replace <root_user> a valid superuser.
mysql --default-character-set=utf8mb4 -u<root_user> -e "grant all on cleanspeak.* to 'cleanspeak'@'localhost' identified by 'cleanspeak'" cleanspeak

# Create CleanSpeak schema, run this command from the directory where you have extracted the CleanSpeak Database Schema zip
mysql --default-character-set=utf8mb4 -ucleanspeak -pcleanspeak cleanspeak < mysql.sql

# Create the cleanspeak database, replace <root_user> a valid superuser.
psql -U<root_user> -c "CREATE DATABASE cleanspeak ENCODING 'UTF-8' LC_CTYPE 'en_US.UTF-8' LC_COLLATE 'en_US.UTF-8' TEMPLATE template0"

# Note, if installing on Windows, the Encoding values are different, replace the previous command with this version.
psql -U<root_user> -c "CREATE DATABASE cleanspeak ENCODING 'UTF-8' LC_CTYPE 'English_United States' LC_COLLATE 'English_United States' TEMPLATE template0;"

# Grant cleanspeak all authority to cleanspeak database, replace <root_user> and <password> with valid superuser credentials.
psql -U<root_user> -c "CREATE ROLE cleanspeak WITH LOGIN PASSWORD '<password>'; GRANT ALL PRIVILEGES ON DATABASE cleanspeak TO cleanspeak; ALTER DATABASE cleanspeak OWNER TO cleanspeak;"

# Create CleanSpeak schema, run this command from the directory where you have extracted the CleanSpeak Database Schema zip
psql -Ucleanspeak cleanspeak < postgresql.sql

license.id=

database.url=jdbc:mysql://localhost:3306/cleanspeak
database.username=cleanspeak
database.password=cleanspeak