Change repository home

By default, the repository is located at “$TOMCAT_HOME/repository”, but you can change it to another location.

Caution

This action must be done with the application stopped.

Understanding the contents of repository folders

In “$TOMCAT_HOME/repository” there are four folders: tmp, index, cache and datastore.

Folder	Backup	Description
tmp	No	This folder contains some temporary files to be shared between several clustered OpenKM instances.
index	No	The folder which contains the Lucene search engine indexes. The content of that folder can be rebuilt. Although it is not mandatory to back up this folder, we recommend doing so.
cache	No	The folder which contains the application’s cached files. For example, for previewing documents, it is sometimes necessary to transform the original document to another format. The conversion consumes a lot of hardware resources; for this reason the application stores these converted files to be reused later. The content of that folder can be cleared without major problems. Although it is not mandatory to back up this folder, we recommend doing so.
datastore	Yes	The folder which contains all binary data for the documents. It is mandatory to back up this folder; otherwise the binary data of the documents could be lost if the server hardware fails.
extraction	Yes	This folder contains the text extracted from the documents stored in OpenKM. A backup is not really necessary, but it may be a time saver.
ocr_templates	Yes	This folder contains the binary data of the OCR templates.

Move entire repository location

• Stop the application
• Move the “$TOMCAT_HOME/repository” to another location.
• Edit the “$TOMCAT_HOME/openkm.properties” file and add the property “repository.home”.
• Start the application

Sample 1

Caution

From OpenKM version 7.1.x and later, when the “repository.home” parameter is set, the file system location of the Lucene index is not affected. You should use the specific parameter named “spring.jpa.properties.hibernate.search.default.indexBase” to move the Lucene index to a new location.

Windows

repository.home=C:/okmrepo

Linux

repository.home=/mnt/okmrepo

Move repository folders individually

Table of properties:

Folder	Property	Default
index	spring.jpa.properties.hibernate.search.backend.directory.root	${catalina.home}/repository/index
tmp	repository.temp.home	${repository.home}/tmp
cache	repository.cache.home	${repository.home}/${tenant.id}/cache
datastore	repository.datastore.home	${repository.home}/${tenant.id}/datastore
extraction	repository.extraction.home	${repository.home}/${tenant.id}/extraction
ocr template	repository.ocr.template.home	${repository.home}/${tenant.id}/ocr_template

Caution

These parameters can be used in combination with the parameters “repository.home” and “tenant.id”.

• Stop the application
• Move the “$TOMCAT_HOME/repository/{folder}” to another location.
• Edit the “$TOMCAT_HOME/openkm.properties” file and add the appropriate property.
• Start the application

Sample

Windows

spring.jpa.properties.hibernate.search.backend.directory.root=C:/lucene/index
repository.datastore.home=D:/okm/${repository.home}/datastore
repository.cache.home=D:/okm/${repository.home}/cacherepository.temp.home=D:/okm/${repository.home}/tmp
repository.ocr.template.home=D:/okm/${repository.home}/cacherepository.temp.home=D:/okm/${repository.home}/ocr_template

Linux

spring.jpa.properties.hibernate.search.backend.directory.root=/mnt/lucene/index
repository.datastore.home=/mnt/okm/${repository.home}/datastore
repository.cache.home=/mnt/okm/${repository.home}/cacherepository.temp.home=/mnt/okm/${repository.home}/tmp
repository.ocr.template.home=/mnt/okm/${repository.home}/cacherepository.temp.home=/mnt/okm/${repository.home}/ocr_template

Use an S3-compatible backend

Each repository folder that has its own “type” property (datastore, cache, extraction, ocr template) can be stored on Amazon S3 (or an S3-compatible service, e.g. MinIO) instead of the local filesystem, chosen independently for each one.

Folder	Type property	Values
datastore	repository.datastore.type	filesystem (default), s3
cache	repository.cache.type	filesystem (default), s3
extraction	repository.extraction.type	filesystem (default), s3
ocr template	repository.ocr.template.type	filesystem (default), s3

When a folder’s type is set to “s3”, the following properties configure the connection. “repository.s3.*” acts as a global default; “repository.{folder}.s3.*” (e.g. “repository.datastore.s3.bucket”) overrides it for that folder only, so different folders can use different buckets/credentials if needed.

Property (global / per-folder)	Description
repository.s3.bucket / repository.{folder}.s3.bucket	S3 bucket name.
repository.s3.region / repository.{folder}.s3.region	AWS region, e.g. eu-west-1. Leave empty to use the AWS SDK default.
repository.s3.endpoint / repository.{folder}.s3.endpoint	Custom endpoint URL. Only needed for S3-compatible on-premises storage (e.g. MinIO); leave empty for real AWS S3.
repository.s3.path-style-access / repository.{folder}.s3.path-style-access	Boolean. Enable for S3-compatible services that require path-style access instead of virtual-hosted-style addressing. false
repository.s3.access-key / repository.{folder}.s3.access-key	AWS access key. May be encrypted with Jasypt ENC(…). If both the global and per-folder access/secret keys are left empty, the AWS default credentials provider chain is used instead (IAM role, environment variables, etc.).
repository.s3.secret-key / repository.{folder}.s3.secret-key	AWS secret key. May be encrypted with Jasypt ENC(…).
repository.{folder}.s3.key-prefix	Key prefix used to build each object’s S3 key, e.g. “tenant_1/shard_1/datastore/…”. No global fallback (each folder needs its own literal directory name). Supports the same “${tenant.id}”/“${shard.id}” placeholders as the filesystem “*.home” properties above, but is otherwise independent of them — changing “repository.{folder}.home” does not affect the S3 key prefix, and vice versa. ${tenant.id}/${shard.id}/

All of the above are set in “$TOMCAT_HOME/openkm.properties” and require a restart to take effect.

Caution

Switching a folder’s type from “filesystem” to “s3” does not move its existing content automatically — new content goes to the new backend, but content already on disk stays on disk and becomes unreachable once the switch is made. Before switching, use the Global Content Migration utility (Administration > Utilities > Repository > Global Content Migration) to copy existing content into S3 first; run it once, then run it again right before the actual switch to also pick up anything written in between.

Troubleshooting

Windows mapped network drive is not working

Caution

We encourage you not to use network storage (NAS or Samba) for storing the repository. Network issues will affect the repository; we consider this a dangerous configuration.

There seem to be restrictions when using a network drive (mapped with the “net use” command) and running the application as a service. To solve this, it is necessary to create a link between the UNC path and the file system.

MKLINK /D C:\okm-repository \\192.168.1.36\eDocuments\okm-repository

Note

In most cases, it will be necessary to use a standard user to run the OpenKM service instead of the default. Take a look at the OpenKM Windows service configuration to change the default “Local system user” to your own.