Installing on Ubuntu and Debian (Manual)

This page contains obsolete information and will be removed in a 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

In case to configure OpenKM in a cluster or sharding model, please, before starting with the installation process, read the sections:

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

In case 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

and 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 if the open file limits are 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 your installed one, but we recommend the latest 1.8 release.

Install Java

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

In the case of Ubuntu 20.04 may be the OpenJDK-8-JDK is not by default in the repositories; try to execute the next command line if you are in this trouble:

$> add-apt-repository universe

In the case of Ubuntu

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

In the case of 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, it would help if you switched to SID (not recommendable for production servers) or used the packages from https://adoptopenjdk.net/. Run these sentences 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.

Also, you can install MariaDB, which replaces MySQL in the latest versions:

$ sudo apt-get install mariadb-server

Change MySQL root password

Do it only if it's necessary to change 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;

MySQL, in this case, has not been started at service, and the process must be killed to stop MySQL and 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;

MySQL, in this case, has not been started in service, and the process must be killed to stop MySQL and start it again as a service.

More information at MySQL: Reseting 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

and 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 numeration name can be altered to upgrade 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 copying 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 would like 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 has enabled if your database is MySQL.

First-time application start:

$ service tomcat start

To see the startup process can execute the 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 by 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