OpenKM 6.3 - CE

Hardware and software requirements

Installation

Installing on Ubuntu and Debian

Installing on RedHat and CentOS

Installing on Windows

Using the installer

Using Docker

Database

Backup and restore

Instance replication

Setup

Troubleshooting

Administration guide

User guide

Migration guide

Development

Installing on Ubuntu and Debian

Preliminaries

Check disk size

$ df -h

Create user named openkm

$ sudo adduser openkm

You can easily generate random passwords at:

Check if partners channels are enabled

$ cat /etc/apt/sources.list

In case they are not enabled, 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 ulimit

$ 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 files limits are now updated.

Checking Java version

$ java -version

If Java is correctly installed on your computer, the name and version of the Java virtual machine is 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 be different depending on your installed one, but we always recommend the latest 1.8 release.

Install Java

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

In case of Ubuntu

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

In case of Debian

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

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 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. 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 at service. The process must be killed to stop MySQL and start it again as a service

More information at MySQL : Reseting permissions.

Check InnoDB is default MySQL engine

$ mysql -h localhost -u root -p

> show engines;

It should looks something like this:

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

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

$ vim /etc/mysql/my.cnf

and under [mysqld] add

default-storage-engine = innodb

After changing 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 OpenKM and Tomcat bundle

$ cd /home/openkm

$ unzip openkm-6.3.2-community-tomcat-bundle.zip

The tomcat version numeration name can be altered in order 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/tomcat

#!/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
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 other user to start the service or your $TOMCAT_HOME is not /home/openkm/tomcat

Make it executable:

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

Update the run-levels:

$ sudo update-rc.d tomcat defaults

Check the service

Start the service:

$ sudo service tomcat start

Stop the service:

$ sudo service tomcat stop

Installing third-party software

Software	Required	Command
LibreOffice or OpenOffice	Yes	$ apt-get install libreoffice
Tesseract	No	$ apt-get install tesseract-ocr tesseract-ocr-eng Depending on your locale you would like to install other language file.
Clamav	No	$ apt-get install clamav
Imagemagick	Yes	$ apt-get install imagemagick
Ghostscript	Yes	$ apt-get install ghostscript

Start application

Check OpenKM.cfg parameters

$ vim /home/openkm/tomcat/OpenKM.cfg

Your configuration should be something like this:

# OpenKM Hibernate configuration values
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
hibernate.hbm2ddl=create

Ensure hibernate.dialect=org.hibernate.dialect.MySQL5Dialect is 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/log/catalina.log

When application is started you'll see in 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 > 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');

Other common additional configurations setup

OpenKM comes with a lot of configuration parameters. Please make sure to review: Recommended configuration parameters.

Restart installation from scratch

The OpenKM first startup does some background configurations like filesystem folder creation, changes in the OpenKM.cfg what only happens during the first startup.

Sometimes maybe some mistake in OpenKM configuration, for example, wrong database connection or similar issues during the first startup what raise and application failure. To restart the installation from scratch we suggest following the next steps.

Ensure OpenKM is stopped.
Edit the OpenKM.cfg and set the parameter hibernate.hbm2ddl=create
In case issue with database connection, we suggest checking the connection from the OpenKM server. Remember some databases require enabling the user to gain connection from a server ( specific IP, range of IP, any server ).
Delete the folder named "repository"
Start OpenKM.

Table of contents [ Hide Show ]

Preliminaries

Check disk size
Create user named openkm
Check if partners channels are enabled
Check server configuration
Increase ulimit

Checking Java version

Install Java
Set OpenJDK 1.8 as your default Java version

Installing database

Change MySQL root password

Method 1
Method 2
Method 3
Method 4

Check InnoDB is default MySQL engine
Create database

Installing OpenKM and Tomcat bundle
Configuring Tomcat as a service

Check the service
Installing third-party software

Start application

Check OpenKM.cfg parameters

Other common additional configurations setup
Restart installation from scratch

Installing on Ubuntu and Debian

Preliminaries

Check disk size

$ df -h

Create user named openkm

$ sudo adduser openkm

You can easily generate random passwords at:

Check if partners channels are enabled

$ cat /etc/apt/sources.list

In case they are not enabled, 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 ulimit

$ 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 files limits are now updated.

Checking Java version

$ java -version

If Java is correctly installed on your computer, the name and version of the Java virtual machine is 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 be different depending on your installed one, but we always recommend the latest 1.8 release.

Install Java

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

In case of Ubuntu

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

In case of Debian

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

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 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. 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 at service. The process must be killed to stop MySQL and start it again as a service

More information at MySQL : Reseting permissions.

Check InnoDB is default MySQL engine

$ mysql -h localhost -u root -p

> show engines;

It should looks something like this:

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

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

$ vim /etc/mysql/my.cnf

and under [mysqld] add

default-storage-engine = innodb

After changing 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 OpenKM and Tomcat bundle

$ cd /home/openkm

$ unzip openkm-6.3.2-community-tomcat-bundle.zip

The tomcat version numeration name can be altered in order 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/tomcat

#!/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
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 other user to start the service or your $TOMCAT_HOME is not /home/openkm/tomcat

Make it executable:

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

Update the run-levels:

$ sudo update-rc.d tomcat defaults

Check the service

Start the service:

$ sudo service tomcat start

Stop the service:

$ sudo service tomcat stop

Installing third-party software

Software	Required	Command
LibreOffice or OpenOffice	Yes	$ apt-get install libreoffice
Tesseract	No	$ apt-get install tesseract-ocr tesseract-ocr-eng Depending on your locale you would like to install other language file.
Clamav	No	$ apt-get install clamav
Imagemagick	Yes	$ apt-get install imagemagick
Ghostscript	Yes	$ apt-get install ghostscript

Start application

Check OpenKM.cfg parameters

$ vim /home/openkm/tomcat/OpenKM.cfg

Your configuration should be something like this:

# OpenKM Hibernate configuration values
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
hibernate.hbm2ddl=create

Ensure hibernate.dialect=org.hibernate.dialect.MySQL5Dialect is 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/log/catalina.log

When application is started you'll see in 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 > 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');

Other common additional configurations setup

OpenKM comes with a lot of configuration parameters. Please make sure to review: Recommended configuration parameters.

Restart installation from scratch

The OpenKM first startup does some background configurations like filesystem folder creation, changes in the OpenKM.cfg what only happens during the first startup.

Ensure OpenKM is stopped.
Edit the OpenKM.cfg and set the parameter hibernate.hbm2ddl=create
In case issue with database connection, we suggest checking the connection from the OpenKM server. Remember some databases require enabling the user to gain connection from a server ( specific IP, range of IP, any server ).
Delete the folder named "repository"
Start OpenKM.