Installing on Ubuntu and Debian (Manual)

This page contains obsolete information and will be removed in the near future.

This section of the documentation tries to describe how to install OpenKM manually. An OpenKM Installer tool does most things automatically; more information at Using the installer.

Preliminaries

If you plan to configure OpenKM in a cluster or sharding model, please read the following sections before starting the installation process:

Check disk size

$ df -h

Create a user named openkm

$ sudo adduser openkm

You can easily generate random passwords at https://www.random.org/passwords.

Check if partners' channels are enabled

$ cat /etc/apt/sources.list

If they are not enabled, please enable them.

$ sudo vim /etc/apt/sources.list

$ sudo apt-get update

Check server configuration

$ wget -Nc smxi.org/inxi
$ sudo chmod +x inxi
$ sudo ./inxi -F

Increase limit

$ sudo vim /etc/pam.d/su

Uncomment the following line

#session required pam_limits.so

session required pam_limits.so

$ sudo vim /etc/security/limits.conf

Add the following lines to the end of the file (before the line # End of file)

* soft nofile 6084

* hard nofile 6084

Now reboot the server, execute ulimit -n, and check whether the open file limits have been updated.

Checking Java version

$ java -version

If Java is correctly installed on your computer, the name and version of the Java virtual machine are displayed:

openjdk version "1.8.0_212"
OpenJDK Runtime Environment (build 1.8.0_212-8u212-b03-0ubuntu1.18.04.1-b03)
OpenJDK 64-Bit Server VM (build 25.212-b03, mixed mode)

The Java version may differ depending on the version you have installed, but we recommend the latest 1.8 release.

Install Java

Perform these steps only if Java 8 is not already installed on your server.

On Ubuntu 20.04, OpenJDK-8-JDK may not be available in the default repositories; if this is the case, try executing the following command:

$> add-apt-repository universe

For Ubuntu

$ sudo apt-get update
$ sudo apt-get install openjdk-8-jdk

For Debian

$ su -
$ apt-get update
$ apt-get install openjdk-8-jdk
$ exit

In the case of Debian 10 "Buster," Java 8 packages are not included in the default repositories. Hence, you may need to switch to SID (not recommended for production servers) or use the packages from https://adoptopenjdk.net/. Run these commands as root:

$ apt install wget gnupg software-properties-common

$ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | apt-key add -

$ add-apt-repository --yes https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/

$ apt-get update

$ apt-get install adoptopenjdk-8-hotspot

Set OpenJDK 1.8 as your default Java version.

Perform this only if Java 8 is not your default Java version.

$ sudo update-alternatives --config java

Installing database

Install MySQL if you do not have it already installed:

$ sudo apt-get install mysql-server

When you install MySQL, the installer will ask you for a password for the root user. Keep this password handy.

You can also install MariaDB, which replaces MySQL in the latest versions:

$ sudo apt-get install mariadb-server

Change MySQL root password

Do this only if it's necessary to change the MySQL root password.

Method 1

$ /usr/bin/mysqladmin -u root -h localhost password 'password.'

Method 2

$ sudo /etc/init.d/mysql stop
$ sudo mysqld --skip-grant-tables &
$ mysql -u root MySQL
> UPDATE user SET Password=PASSWORD('YOURNEWPASSWORD') WHERE User='root';
> FLUSH PRIVILEGES;
> exit;

In this case, MySQL is not running as a service; you must kill the process to stop MySQL and then start it again as a service.

Method 3

$ mysql
> UPDATE mysql.user SET Password=PASSWORD('MyNewPass') WHERE User='root';
> flush privileges;

Method 4

$ sudo /etc/init.d/mysql stop
$ mysqld_safe --skip-grant-tables &
$ mysql -u root mysql
> UPDATE user SET Password=PASSWORD('YOURNEWPASSWORD') WHERE User='root';
> FLUSH PRIVILEGES;
> exit;

In this case, MySQL is not running as a service; you must kill the process to stop MySQL and then start it again as a service.

More information at MySQL: Resetting permissions.

Check InnoDB is the default MySQL engine

$ mysql -h localhost -u root -p

> show engines;

It should look something like this:

| InnoDB | DEFAULT | Supports transactions, row-level locking, and foreign keys | YES | YES | YES |

If it is not default, modify /etc/mysql/my.cnf

$ vim /etc/mysql/my.cnf

Under [mysqld], add

default-storage-engine = innodb

After changing the default MySQL engine, the MySQL service must be restarted to take effect.

Create database

CREATE DATABASE okmdb DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_bin;
CREATE USER openkm@localhost IDENTIFIED BY 'password';
GRANT ALL ON okmdb.* TO openkm@localhost WITH GRANT OPTION;

Installing Tomcat

$ cd /home/openkm

$ unzip Tomcat-8.5.69.zip

The Tomcat version numbering may vary when upgrading to a major version.

Configuring Tomcat as a service

For security reasons, you shouldn't run Tomcat as root. It is better to use the user named openkm.

Create a file with the script:

$ sudo vim /etc/init.d/openkm

#!/bin/sh
 
### BEGIN INIT INFO
# Provides:          tomcat
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start and stop Apache Tomcat
# Description:       Enable Apache Tomcat service provided by daemon.
### END INIT INFO
 
ECHO=/bin/echo
TEST=/usr/bin/test
TOMCAT_USER=openkm
TOMCAT_HOME=/home/openkm/tomcat-8.5.69
TOMCAT_START_SCRIPT=$TOMCAT_HOME/bin/startup.sh
TOMCAT_STOP_SCRIPT=$TOMCAT_HOME/bin/shutdown.sh
 
$TEST -x $TOMCAT_START_SCRIPT || exit 0
$TEST -x $TOMCAT_STOP_SCRIPT || exit 0
 
start() {
    $ECHO -n "Starting Tomcat"
    su - $TOMCAT_USER -c "$TOMCAT_START_SCRIPT &"
    $ECHO "."
}
 
stop() {
    $ECHO -n "Stopping Tomcat"
    su - $TOMCAT_USER -c "$TOMCAT_STOP_SCRIPT 60 -force &"
    while [ "$(ps -fu $TOMCAT_USER | grep java | grep tomcat | wc -l)" -gt "0" ]; do
        sleep 5; $ECHO -n "."
    done
    $ECHO "."
}
 
case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    restart)
        stop
        sleep 30
        start
        ;;
    *)
        $ECHO "Usage: tomcat {start|stop|restart}"
        exit 1
esac
exit 0

The script must be changed if you use another user to start the service or your $TOMCAT_HOME is not /home/openkm/tomcat-8.5.69

Make it executable:

$ sudo chmod 755 /etc/init.d/openkm

Update the run-levels:

$ sudo update-rc.d openkm defaults

Check the service

Start the service:

$ sudo service openkm start

Stop the service:

$ sudo service openkm stop

Installing OpenKM

With Tomcat stopped, copy the openkm.war file into /home/openkm/tomcat-8.5.69/webapps

$ cp openkm.war /home/openkm/tomcat-8.5.69/webapps

Installing third-party software

Software	Required	Command
LibreOffice	Yes	$ apt-get install libreoffice
Tesseract	No	$ apt-get install tesseract-ocr tesseract-ocr-eng Depending on your locale, you may want to install another language file.
ClamAV	No	$ apt-get install ClamAV
ImageMagick	Yes	$ apt-get install imagemagick
Ghostscript	Yes	$ apt-get install ghostscript

Start application

Check openkm.properties parameters

$ vim /home/openkm/tomcat-8.5.69/openkm.properties

Your configuration should be something like this:

# OpenKM Hibernate configuration values
spring.jpa.properties.hibernate.dialect=com.openkm.db.dialect.MySQL5InnoDBDialect
spring.jpa.hibernate.ddl-auto=create-only

Ensure spring.jpa.properties.hibernate.dialect=com.openkm.db.dialect.MySQL5InnoDBDialect is enabled if your database is MySQL.

First-time application start:

$ service tomcat start

To see the startup process, execute the following command:

$ tail -f /home/openkm/tomcat-8.5.69/log/catalina.log

When the application is started, you'll see in the log file the lines:

2015-07-04 18:28:10,680 [main] INFO  org.apache.coyote.http11.Http11Protocol - Starting ProtocolHandler ["http-bio-0.0.0.0-8080"]
2015-07-04 18:28:10,688 [main] INFO  org.apache.coyote.ajp.AjpProtocol - Starting ProtocolHandler ["ajp-bio-127.0.0.1-8009"]
2015-07-04 18:28:10,692 [main] INFO  org.apache.catalina.startup.Catalina - Server startup in 41456 ms

The application will be accessible at http://YOUR_IP:8080/OpenKM using the user okmAdmin with password admin. (Do not forget to change it!) For more information about Manage users and roles.

Configure default extensions:

Go to Administration > Utilities > Database query and execute:

INSERT INTO OKM_EXTENSION (EXT_UUID, EXT_NAME) VALUES ('808e7a42-2e73-470c-ba23-e4c9d5c3a0f4', 'Live Edit');
INSERT INTO OKM_EXTENSION (EXT_UUID, EXT_NAME) VALUES ('58392af6-2131-413b-b188-1851aa7b651c', 'HTML Editor 4');
INSERT INTO OKM_PROFILE_MSC_EXTENSION (PEX_ID, PEX_EXTENSION) VALUES (1, '808e7a42-2e73-470c-ba23-e4c9d5c3a0f4');
INSERT INTO OKM_PROFILE_MSC_EXTENSION (PEX_ID, PEX_EXTENSION) VALUES (1, '58392af6-2131-413b-b188-1851aa7b651c');

Troubleshooting

In the case of Debian 10, how to install Java:

$ apt-get install software-properties-common
$ apt-add-repository 'deb http://security.debian.org/debian-security stretch/updates main'
$ apt-get update

$ apt-get install openjdk-8-jdk