Installation and Migration¶

Windows¶

1. Download the Refine .msi installer file.
2. Double-click the application file and follow the on-screen installer prompts.
3. You will be asked for an installation location.
4. Locate the application in the Windows Start menu or on the desktop and start it.
5. The Refine application opens at http://localhost:7333/.

MacOS¶

1. Download the Refine .dmg file.
2. Double-click it and get a virtual disk on your desktop.
3. Copy the program from the virtual disk to your hard disk Applications folder.
4. Locate the application on the desktop and start it.
5. The Refine application opens at http://localhost:7333/.

Linux¶

1. Download the Refine .deb or .rpm file.
2. Install the package:

• Debian and derivatives: sudo dpkg -i <package-name>.deb
• Redhat and derivatives: sudo rpm -i  <package-name>.rpm
• CentOS and derivatives: sudo yum install <package-name>

3. Alternatively, double-click the package.
4. Locate the application on the desktop and start it.
5. The Refine application opens at http://localhost:7333/.

Configuring Native Refine¶

Native Refine uses two configuration files:

• {ontorefine.dist}/Ontotext Refine.cfg are Java launcher properties. See JVM Configuration for details.
  • On Windows, this is \\Users\\<username>\\AppData\\Local\\Ontotext Refine\\app\\Ontotext Refine.cfg
• {user.home}/OntoRefine/ontorefine.properties are Refine properties. See Refine Configuration Parameters for details.

• On Windows, this is \\Users\\<username>\\AppData\\Roaming\OntoRefine\ontorefine.properties
• You can change this location using the Java property ontorefine.config.path or environment variable ONTOREFINE_CONFIG_PATH.

Once you have started the native application, a small icon appears in the statusbar/menu/tray area. It allows you to check if the application is running, stop it or change the configuration settings. Additionally, an application window is opened, where you can open the Refine web app, go to the Refine documentation, configure settings, and see all log files. You can reopen this window by choosing Show Refine window from the statusbar icon menu.

In addition, a few of the parameters (for connecting to GraphDB) can be set in the Refine web app.

Stopping Native Refine¶

To stop the application, simply quit it from the statusbar/menu/tray area icon, or close the Refine application window.

Running Standalone Refine¶

1. Download the Refine distribution archive and unpack it.
2. Start Refine by executing the ontorefine startup script located in the bin directory of the Refine distribution.

A message appears in the console telling you that Refine has been started. You can access the Refine client at http://localhost:7333/ in your browser.

Configuring Refine Server¶

See Refine Configuration Parameters for a description of Refine settings.

Quick Start¶

The following Docker Compose file can be used to quickly get Refine up and running.

version: "3"

services:
  refine:
    image: ontotext/refine
    restart: unless-stopped
    environment:
      SERVER_HOST: localhost
    ports:
      - "7333:7333"
    volumes:
      - refine_data:/opt/ontorefine/data

volumes:
  refine_data:

After saving the Docker Compose file, start it by executing the next shell command in the same folder as the file:

docker-compose up -d

Refine is accessible by default at http://localhost:7333/.

Configuring Docker¶

You can pass any of the configurations parameters described below as environment variables in uppercase convention. For example, server.host should be written as SERVER_HOST.

Refine Configuration Parameters¶

You can assign configuration parameters in three ways:

• Edit the configuration file.
• Set corresponding environment variables. E.g. the property server.host should be written as SERVER_HOST.
• Add command-line options to the startup script. You can also pass JVM options that way. For example, to change the config file location, Refine port number, and set Java max heap, use:

ontorefine -Dontorefine.config.path=<your-config-file> -Dserver.port=<your-port> -Xmx4g

If the same parameter is set in multiple locations, the following order of precedence applies: config file < environment variables < command-line arguments.

Refine takes the following configuration parameters:

• ontorefine.config.path: Location of Refine config file. Created on first startup of Native Refine. Can be changed using the Java command-line property ontorefine.config.path or environment variable ONTOREFINE_CONFIG_PATH, but not within the config file itself. Defaults:

  • On Mac: {user.home}/.ontorefine/ontorefine.properties
  • On Windows: \\Users\\<username>\\AppData\\Roaming\OntoRefine\ontorefine.properties
  • On Linux: {user.home}/.ontorefine/ontorefine.properties

• ontorefine.data: Location of Refine data (project files and workspace.json). Defaults:

  • On Mac: {user.home}/.ontorefine
  • On Windows: \\Users\\<username>\\AppData\\Roaming\OntoRefine\\refine
  • On Linux: {user.home}/.ontorefine

• ontorefine.dist: Refine installation directory. Can be set during installation of Native Refine. Should not be edited, unless Refine is moved manually. Defaults:

  • On Mac: /Applications/Ontotext Refine.app/Contents/app
  • On Windows: \\Users\\<username>\\AppData\\Local\\Ontotext Refine\\app
  • On Linux: /opt/ontorefine/lib/app/

• server.host: server on which Refine runs. Useful for CORS configurations. Default: your machine’s hostname

• server.port: port on which the Refine server responds. Default: 7333

• graphdb.address: URL address of the GraphDB instance that Refine asks for namespaces and class/property autocompletion. Default in the Setup menu of the web app: http://localhost:7200

• graphdb.repository: ID of the GraphDB repository that Refine works with. Default in the Setup menu of the web app: refine

• graphdb.auth.method: Authentication method used for GraphDB Access Control. Case-insensitive. Default: NONE. Possible settings:

  • NONE: used only when GraphDB security is OFF. This should only be used on a local network not connected to the internet.

  • BASIC: the username and password are sent in a header as plain text (see Basic authentication). Sending the password as plain text is insecure, so it is important to use Encryption in Transit (i.e. https) to improve security.

    • graphdb.auth.basic.username: username for Basic authentication.
    • graphdb.auth.basic.credentials: password for Basic authentication.

  • GDB: token-based authentication, also used by GraphDB Workbench (see GDB authentication). Refine uses the GraphDB login API method to obtain a token: this happens on Refine startup, and whenever the token expires. Token expiration is controlled by the graphdb.auth.token.validity parameter in GraphDB (default: 30d). Refine uses the following parameters to perform GraphDB login:

    • graphdb.auth.gdb.username: username for GDB authentication.
    • graphdb.auth.gdb.credentials: password for GDB authentication.

JVM Configuration¶

You can use the following environment variables to control Java startup parameters:

• ONTOREFINE_JAVA_OPTS: Sets additional Java parameters (-D or -X)
• ONTOREFINE_JAVA_32BIT: If set to true, configures Refine to run on 32bit Java
• ONTOREFINE_MIN_MEM: Sets the Java minimum heap size (-Xms option).
• ONTOREFINE_MAX_MEM: Sets the Java maximum heap size (-Xmx option).
• ONTOREFINE_HEAP_SIZE: Sets the Java minimum and maximum heap size (-Xms and -Xmx option).
• ONTOREFINE_HEAP_NEWSIZE: Sets the initial and maximum heap size for the young generation (-Xmn option).
• ONTOREFINE_GC_LOG: If set to true, enables the logging of Java garbage collection.
• ONTOREFINE_GC_LOG_FILE: Specifies a custom file for logging of Java garbage collection.

Other Java options are defined at the end of the file {ontorefine.dist}/Ontotext Refine.cfg. Each java-options= line provides a single argument passed to the JVM when it starts (-cp means “class path”).

Here are the options with their default settings on Windows:

[JavaOptions]
java-options=-Djpackage.app-version=1.0
java-options=-cp
java-options=$APPDIR\ontorefine-native-app.jar;$APPDIR\lib\*
java-options=-Dfile.encoding=UTF-8
java-options=-Dontorefine.dist=$APPDIR
java-options=--add-exports
java-options=jdk.management.agent/jdk.internal.agent=ALL-UNNAMED
java-options=--add-opens

java-options=java.base/java.lang=ALL-UNNAMED

It is recommended not to remove or change any of the existing options provided with the installation. You can add your own options at the end.

For example, if you want to run Refine with 8 Gb of maximum heap memory, you can set the following option:

java-options=-Xmx8g

The launcher spawns the Refine application within the same JVM that it operates in, so you cannot change JVM options from the command line.