CINXE.COM

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-11346334-10']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> <title>Installation and Migration — Refine 1.2.0 documentation</title> <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/bootstrap.min.css" type="text/css" /> <link rel="stylesheet" href="_static/css/bootstrap-ontotext-theme.css" type="text/css" /> <link rel="stylesheet" href="_static/css/custom.css" type="text/css" /> <script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <script src="_static/language_data.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Loading and Saving Data Using Refine" href="loading-data-using-ontorefine.html" /> <link rel="prev" title="Overview and features" href="index.html" /> <meta charset='utf-8'> <meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'> <meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'> <meta name="apple-mobile-web-app-capable" content="yes">   <link rel="apple-touch-icon" sizes="180x180" href="/ontorefine/1.2/_static/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/ontorefine/1.2/_static/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/ontorefine/1.2/_static/favicon-16x16.png"> <link rel="manifest" type="application/manifest+json" href="/ontorefine/1.2/_static/site.webmanifest">  <script src="/ontorefine/1.2/_static/js/jquery-1.12.4.min.js"></script> <script src="/ontorefine/1.2/_static/js/jquery-fix.js"></script> <script src="/ontorefine/1.2/_static/bootstrap-sphinx.js"></script>  <script src="https://cdnjs.cloudflare.com/ajax/libs/tether/1.4.0/js/tether.min.js" integrity="sha384-DztdAPBWPRXSA/3eYEEUWrWCy7G5KFbe8fFjk5JAIxUYHKkDx6Qin1DkWx51bBrb" crossorigin="anonymous"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.6/js/bootstrap.min.js" integrity="sha384-vBWWzlZJ8ea9aCX4pEW3rVHjgjt7zpkNpZk+02D9phzyeVkE+jo0ieGizqPLForn" crossorigin="anonymous"></script> <script type="text/javascript"> //temporary solution to remove sphinx css $(document).ready(function() { $("link[href*='basic.css']").remove(); $("link[href*='bootstrap-sphinx.css']").remove(); }); //hide the other collapsible elements on collapsing a menu item var $myGroup = $('#side-menu-accoridion'); $myGroup.on('show.bs.collapse','.collapse', function() { $myGroup.find('.collapse.show').collapse('hide'); }); $(function () { $('[data-toggle="tooltip"]').tooltip(); $('#scrollToTop').click( function() { $('html, body').animate({scrollTop: '0px'}, 300); }); }); </script>   <script src="https://cdn.jsdelivr.net/react/15.4.2/react.min.js"></script> <script src="https://cdn.jsdelivr.net/react/15.4.2/react-dom.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/jazzyray/sphinx-graphiql@master/static/graphiql/graphiql.min.js"></script> <link href="https://cdn.jsdelivr.net/gh/jazzyray/sphinx-graphiql@master/static/graphiql/graphiql.css" rel="stylesheet"> <link href="https://cdn.jsdelivr.net/gh/jazzyray/sphinx-graphiql@a048f5e9c6fb3932d7ba3bcea8c56e1d918903d0/static/styles.css" rel="stylesheet"> <meta name="msapplication-TileImage" content="/documentation/home/images/visual_Logo_GraphDB_02_12_2015.png"> </head><body> <div id="page"> <div id="sidebar" class="bs-sidenav bg-lightgray" data-spy="affix"> <div class="hidden-xs hidden-sm"> <div class="bg-secondary d-flex"> <a href="/ontorefine/1.2/index.html" class="brand" title="Refine 1.2"> <img src="/ontorefine/1.2/_static/ontorefine-logo.svg" alt="Refine logo" height="44" class="logo"> <span>1.2</span> </a> <a class="ml-auto btn btn-primary hidden-lg-up d-flex" data-toggle="collapse" href="#collapseSideNav" aria-expanded="false" aria-controls="collapseExample"> <span class="icon-hbars align-self-center"></span> </a> </div> <div id="collapseSideNav" class="hidden-mobile-nav"> <div class="p-3"> <form action="/ontorefine/1.2/search.html" method="get"> <div class="input-group input-group-sm"> <span class="input-group-addon icon"><span class="icon-search icon-lg text-muted"></span></span> <input type="text" name="q" class="form-control" placeholder="Search the documentation..."> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </div> </form> <div class="mt-3"> <div class="dropdown d-inline-block"> <button class="btn btn-link dropdown-toggle p-0" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"> Refine </button> <span class="dropdown-menu" aria-labelledby="dropdownMenuButton"> <script type="text/javascript"> var xmlHttp = new XMLHttpRequest(); // TODO what do we do with this services.txt? xmlHttp.open( "GET", "https://platform.ontotext.com/services.txt", false ); xmlHttp.send( null ); var services = xmlHttp.responseText; var servicesSplit = services.split("\n"); for (var i = 0; i < servicesSplit.length; i++) { var serviceSplit = servicesSplit[i]; if (serviceSplit.length !== 0) { document.write('<a class="dropdown-item" href="/' + serviceSplit.split(",")[1] + '">' + serviceSplit.split(",")[0] + '</a>'); } } </script> </span> </div> </div> </div> <div class="sidebar-menu"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="index.html">Overview and features</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Installation and Migration</a><ul> <li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a><ul> <li class="toctree-l3"><a class="reference internal" href="#requirements">Requirements</a></li> <li class="toctree-l3"><a class="reference internal" href="#running-refine">Running Refine</a></li> <li class="toctree-l3"><a class="reference internal" href="#native-launchers">Native Launchers</a></li> <li class="toctree-l3"><a class="reference internal" href="#standalone-server">Standalone Server</a></li> <li class="toctree-l3"><a class="reference internal" href="#docker">Docker</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#migrating-existing-projects-from-graphdb-9">Migrating Existing Projects from GraphDB 9</a><ul> <li class="toctree-l3"><a class="reference internal" href="#manual-migration">Manual Migration</a></li> <li class="toctree-l3"><a class="reference internal" href="#bulk-migration">Bulk Migration</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="loading-data-using-ontorefine.html">Loading and Saving Data Using Refine</a></li> <li class="toctree-l1"><a class="reference internal" href="rdfizing.html">RDF-izing Tabular Data</a></li> <li class="toctree-l1"><a class="reference internal" href="ontorefine-cli.html">Ontotext Refine CLI</a></li> <li class="toctree-l1"><a class="reference internal" href="extensions.html">Installing Refine Extensions</a></li> <li class="toctree-l1"><a class="reference internal" href="release-notes.html">Release Notes</a></li> <li class="toctree-l1"><a class="reference internal" href="additional-resources.html">Additional Resources</a></li> </ul> </div> <hr class="m-0">  <div class="sidebar-menu"> <ul id="side-menu-accoridion" role="tablist" aria-multiselectable="true"> <li class="toctree-l1"> <a data-toggle="collapse" data-parent="#side-menu-accoridion" href="#collapse7" aria-expanded="false" aria-controls="collapse7"> Previous versions </a> <ul id="collapse7" class="collapse" role="tabpanel" aria-labelledby="heading7" aria-expanded="true">  <li><a class="menu-item-link" href="/ontorefine/1.0/">Ontotext Refine 1.0</a></li> </ul> </li> </ul> </div></div> </div> </div> <div class="main-container pb-5"> <div class="container-fluid"> <div class="section" id="installation-and-migration"> <h1>Installation and Migration<a class="headerlink" href="#installation-and-migration" title="Permalink to this headline">¶</a></h1> <div class="contents local topic" id="what-s-in-this-document"> <p class="topic-title"><cite>What’s in this document?</cite></p> <ul class="simple"> <li><a class="reference internal" href="#installation" id="id8">Installation</a><ul> <li><a class="reference internal" href="#requirements" id="id9">Requirements</a></li> <li><a class="reference internal" href="#running-refine" id="id10">Running Refine</a></li> <li><a class="reference internal" href="#native-launchers" id="id11">Native Launchers</a><ul> <li><a class="reference internal" href="#windows" id="id12">Windows</a></li> <li><a class="reference internal" href="#macos" id="id13">MacOS</a></li> <li><a class="reference internal" href="#linux" id="id14">Linux</a></li> <li><a class="reference internal" href="#configuring-native-refine" id="id15">Configuring Native Refine</a></li> <li><a class="reference internal" href="#stopping-native-refine" id="id16">Stopping Native Refine</a></li> </ul> </li> <li><a class="reference internal" href="#standalone-server" id="id17">Standalone Server</a><ul> <li><a class="reference internal" href="#running-standalone-refine" id="id18">Running Standalone Refine</a></li> <li><a class="reference internal" href="#configuring-refine-server" id="id19">Configuring Refine Server</a></li> </ul> </li> <li><a class="reference internal" href="#docker" id="id20">Docker</a><ul> <li><a class="reference internal" href="#quick-start" id="id21">Quick Start</a></li> <li><a class="reference internal" href="#configuring-docker" id="id22">Configuring Docker</a></li> <li><a class="reference internal" href="#refine-configuration-parameters" id="id23">Refine Configuration Parameters</a></li> <li><a class="reference internal" href="#jvm-configuration" id="id24">JVM Configuration</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#migrating-existing-projects-from-graphdb-9" id="id25">Migrating Existing Projects from GraphDB 9</a><ul> <li><a class="reference internal" href="#manual-migration" id="id26">Manual Migration</a></li> <li><a class="reference internal" href="#bulk-migration" id="id27">Bulk Migration</a></li> </ul> </li> </ul> </div> <div class="section" id="installation"> <h2><a class="toc-backref" href="#what-s-in-this-document">Installation</a><a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2> <div class="section" id="requirements"> <h3><a class="toc-backref" href="#what-s-in-this-document">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h3> <p>It is recommended to run Refine with:</p> <ul class="simple"> <li>At least 1 gigabyte of memory.</li> <li>At least 256 megabytes of disk space.</li> <li>Java Runtime Environment or Java SE Development Kit versions between 11 and 15<ul> <li>The recommended JRE is <cite>Temurin-11.0.15+10</cite>.</li> <li>Java is not required for native installations, which include that JRE</li> <li>We recommend using Refine with 64-bit version of Java</li> </ul> </li> </ul> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">Refine is an in-memory application, meaning that it loads the full data of the current project in memory. Disk storage is needed for input files, autosave of the project and its metadata (every minute), and exported files.</p> </div> <p>If you have large data, you should provide more memory. We can define large data as:</p> <ul class="simple"> <li>More than 800,000 total cells.</li> <li>An input size of more than 50 megabytes.</li> <li>More than 50 rows per record.</li> </ul> <table border="1" class="docutils align-default"> <colgroup> <col width="31%" /> <col width="36%" /> <col width="33%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Number of cells</th> <th class="head">Minimal memory</th> <th class="head">Optimal memory</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td>400,000</td> <td>512MB</td> <td>1GB</td> </tr> <tr class="row-odd"><td>800,000</td> <td>1.5GB</td> <td>3GB</td> </tr> <tr class="row-even"><td>2,000,000</td> <td>3GB</td> <td>6GB</td> </tr> <tr class="row-odd"><td>4,000,000</td> <td>6GB</td> <td>12GB</td> </tr> <tr class="row-even"><td>6,000,000</td> <td>8GB</td> <td>16GB</td> </tr> <tr class="row-odd"><td>8,000,000</td> <td>10GB</td> <td>20GB</td> </tr> </tbody> </table> <p>As a rule of thumb, optimal memory grows by 2GB for each million cells.</p> <p>You can run Refine with lower memory, but you are risking an Out of Memory (OOM) exception and we can’t recommend such a deployment.</p> <div class="admonition warning"> <p class="first admonition-title">Warning</p> <p class="last">Resource usage is cumulative for <strong>all</strong> projects that are created or opened in this session. For example, if you try to open two projects, one with 2,000,000 cells and another with 4,000,000 cells, you should have 8GB of memory.</p> </div> <p>If you use the <a class="reference external" href="https://docs.openrefine.org/manual/grelfunctions#crosscell-s-projectname-optional-s-columnname-optional">cross()</a> function in a project, the other project is also opened. This function is useful for <a class="reference external" href="https://github.com/OpenRefine/OpenRefine/wiki/Recipes#combining-datasets">combining datasets</a> between Refine projects.</p> </div> <div class="section" id="running-refine"> <h3><a class="toc-backref" href="#what-s-in-this-document">Running Refine</a><a class="headerlink" href="#running-refine" title="Permalink to this headline">¶</a></h3> <p>Refine can be operated as a desktop or a server application. Choose the one that best suits your needs and follow the steps below to run Refine:</p> <ul class="simple"> <li><a class="reference internal" href="#native"><span class="std std-ref">As a desktop (native) installation</span></a>: For desktop users who want to test out the application. It is very straightforward, sets up an uninstaller, and desktop shortcuts.</li> <li><a class="reference internal" href="#standalone"><span class="std std-ref">As a standalone server</span></a>: Recommended for production. Comes packaged with a preconfigured web server. It offers greater configurability.</li> <li><a class="reference internal" href="#docker"><span class="std std-ref">In a Docker container</span></a>: A stable way to have an installation that “just works”, without having to worry about the specifics of your operating system. See our images on <a class="reference external" href="https://hub.docker.com/r/ontotext/refine/tags">Dockerhub</a>.</li> </ul> </div> <div class="section" id="native-launchers"> <span id="native"></span><h3><a class="toc-backref" href="#what-s-in-this-document">Native Launchers</a><a class="headerlink" href="#native-launchers" title="Permalink to this headline">¶</a></h3> <p>The easiest way to set up and run Refine is to use the native desktop installations. This does not require the use of a console and works with a graphic user interface. For this installation approach, you do not need to download Java, as the application comes with JDK 11 bundled.</p> <p>Go to the <a class="reference external" href="https://www.ontotext.com/products/ontotext-refine/download/">Refine download page</a> and request your copy. You will receive an email with the download link. According to your OS, proceed as follows:</p> <div class="section" id="windows"> <h4><a class="toc-backref" href="#what-s-in-this-document">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h4> <ol class="arabic simple"> <li>Download the Refine <cite>.msi</cite> installer file.</li> <li>Double-click the application file and follow the on-screen installer prompts.</li> <li>You will be asked for an installation location.</li> <li>Locate the application in the Windows Start menu or on the desktop and start it.</li> <li>The Refine application opens at <a class="reference external" href="http://localhost:7333/">http://localhost:7333/</a>.</li> </ol> </div> <div class="section" id="macos"> <h4><a class="toc-backref" href="#what-s-in-this-document">MacOS</a><a class="headerlink" href="#macos" title="Permalink to this headline">¶</a></h4> <ol class="arabic simple"> <li>Download the Refine <cite>.dmg</cite> file.</li> <li>Double-click it and get a virtual disk on your desktop.</li> <li>Copy the program from the virtual disk to your hard disk <strong>Applications</strong> folder.</li> <li>Locate the application on the desktop and start it.</li> <li>The Refine application opens at <a class="reference external" href="http://localhost:7333/">http://localhost:7333/</a>.</li> </ol> </div> <div class="section" id="linux"> <h4><a class="toc-backref" href="#what-s-in-this-document">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h4> <ol class="arabic simple"> <li>Download the Refine <code class="docutils literal notranslate"><span class="pre">.deb</span></code> or <code class="docutils literal notranslate"><span class="pre">.rpm</span></code> file.</li> <li>Install the package:</li> </ol> <blockquote> <div><ul class="simple"> <li>Debian and derivatives: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">dpkg</span> <span class="pre">-i</span> <span class="pre"><package-name>.deb</span></code></li> <li>Redhat and derivatives: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">rpm</span> <span class="pre">-i</span>  <span class="pre"><package-name>.rpm</span></code></li> <li>CentOS and derivatives: <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">yum</span> <span class="pre">install</span> <span class="pre"><package-name></span></code></li> </ul> </div></blockquote> <ol class="arabic simple" start="3"> <li>Alternatively, double-click the package.</li> <li>Locate the application on the desktop and start it.</li> <li>The Refine application opens at <a class="reference external" href="http://localhost:7333/">http://localhost:7333/</a>.</li> </ol> </div> <div class="section" id="configuring-native-refine"> <h4><a class="toc-backref" href="#what-s-in-this-document">Configuring Native Refine</a><a class="headerlink" href="#configuring-native-refine" title="Permalink to this headline">¶</a></h4> <p>Native Refine uses two configuration files:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">{ontorefine.dist}/Ontotext</span> <span class="pre">Refine.cfg</span></code> are Java launcher properties. See <a class="reference internal" href="#jvm-configuration"><span class="std std-ref">JVM Configuration</span></a> for details.<ul> <li>On Windows, this is <code class="docutils literal notranslate"><span class="pre">\\Users\\<username>\\AppData\\Local\\Ontotext</span> <span class="pre">Refine\\app\\Ontotext</span> <span class="pre">Refine.cfg</span></code></li> </ul> </li> <li><code class="docutils literal notranslate"><span class="pre">{user.home}/OntoRefine/ontorefine.properties</span></code> are Refine properties. See <a class="reference internal" href="#refine-configuration-parameters"><span class="std std-ref">Refine Configuration Parameters</span></a> for details.</li> </ul> <blockquote> <div><ul class="simple"> <li>On Windows, this is <code class="docutils literal notranslate"><span class="pre">\\Users\\<username>\\AppData\\Roaming\OntoRefine\ontorefine.properties</span></code></li> <li>You can change this location using the Java property <code class="docutils literal notranslate"><span class="pre">ontorefine.config.path</span></code> or environment variable <code class="docutils literal notranslate"><span class="pre">ONTOREFINE_CONFIG_PATH</span></code>.</li> </ul> </div></blockquote> <p>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 <strong>Show Refine window</strong> from the statusbar icon menu.</p> <blockquote> <div><img alt="_images/nativeLauncher.png" src="_images/nativeLauncher.png" /> </div></blockquote> <p>In addition, a few of the parameters (for connecting to GraphDB) can be set in the Refine web app.</p> </div> <div class="section" id="stopping-native-refine"> <h4><a class="toc-backref" href="#what-s-in-this-document">Stopping Native Refine</a><a class="headerlink" href="#stopping-native-refine" title="Permalink to this headline">¶</a></h4> <p>To stop the application, simply quit it from the statusbar/menu/tray area icon, or close the Refine application window.</p> <div class="admonition hint"> <p class="first admonition-title">Hint</p> <p class="last">On some Linux systems, there is no support for statusbar/menu/tray area. If you have hidden the Refine window, you can quit it by killing the process.</p> </div> </div> </div> <div class="section" id="standalone-server"> <span id="standalone"></span><h3><a class="toc-backref" href="#what-s-in-this-document">Standalone Server</a><a class="headerlink" href="#standalone-server" title="Permalink to this headline">¶</a></h3> <p>The recommended way of running Refine in production use cases is as a standalone server. The server is platform-independent and includes all recommended JVM parameters for immediate use.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The standalone distribution does not package a JDK like the native launcher. Before running Refine, please make sure to have JDK or JRE installed.</p> </div> <div class="section" id="running-standalone-refine"> <h4><a class="toc-backref" href="#what-s-in-this-document">Running Standalone Refine</a><a class="headerlink" href="#running-standalone-refine" title="Permalink to this headline">¶</a></h4> <ol class="arabic simple"> <li>Download the Refine distribution archive and unpack it.</li> <li>Start Refine by executing the <code class="docutils literal notranslate"><span class="pre">ontorefine</span></code> startup script located in the <code class="docutils literal notranslate"><span class="pre">bin</span></code> directory of the Refine distribution.</li> </ol> <p>A message appears in the console telling you that Refine has been started. You can access the Refine client at <a class="reference external" href="http://localhost:7333/">http://localhost:7333/</a> in your browser.</p> </div> <div class="section" id="configuring-refine-server"> <h4><a class="toc-backref" href="#what-s-in-this-document">Configuring Refine Server</a><a class="headerlink" href="#configuring-refine-server" title="Permalink to this headline">¶</a></h4> <p>See <a class="reference internal" href="#refine-configuration-parameters"><span class="std std-ref">Refine Configuration Parameters</span></a> for a description of Refine settings.</p> </div> </div> <div class="section" id="docker"> <span id="id4"></span><h3><a class="toc-backref" href="#what-s-in-this-document">Docker</a><a class="headerlink" href="#docker" title="Permalink to this headline">¶</a></h3> <p>In addition to <a class="reference internal" href="#standalone"><span class="std std-ref">Standalone Server</span></a>, Ontotext Refine is also packaged and distributed as a Docker image.</p> <div class="section" id="quick-start"> <h4><a class="toc-backref" href="#what-s-in-this-document">Quick Start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h4> <p>The following <a class="reference external" href="https://docs.docker.com/compose/">Docker Compose</a> file can be used to quickly get Refine up and running.</p> <div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">version</span><span class="p">:</span> <span class="s">"3"</span> <span class="nt">services</span><span class="p">:</span> <span class="nt">refine</span><span class="p">:</span> <span class="nt">image</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">ontotext/refine</span> <span class="nt">restart</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">unless-stopped</span> <span class="nt">environment</span><span class="p">:</span> <span class="nt">SERVER_HOST</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">localhost</span> <span class="nt">ports</span><span class="p">:</span> <span class="p p-Indicator">-</span> <span class="s">"7333:7333"</span> <span class="nt">volumes</span><span class="p">:</span> <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">refine_data:/opt/ontorefine/data</span> <span class="nt">volumes</span><span class="p">:</span> <span class="nt">refine_data</span><span class="p">:</span> </pre></div> </div> <p>After saving the Docker Compose file, start it by executing the next shell command in the same folder as the file:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>docker-compose up -d </pre></div> </div> <p>Refine is accessible by default at <a class="reference external" href="http://localhost:7333/">http://localhost:7333/</a>.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">It is advisable to update the <code class="docutils literal notranslate"><span class="pre">SERVER_HOST</span></code> environment variable to the actual hostname.</p> </div> </div> <div class="section" id="configuring-docker"> <h4><a class="toc-backref" href="#what-s-in-this-document">Configuring Docker</a><a class="headerlink" href="#configuring-docker" title="Permalink to this headline">¶</a></h4> <p>You can pass any of the configurations parameters described below as environment variables in uppercase convention. For example, <code class="docutils literal notranslate"><span class="pre">server.host</span></code> should be written as <code class="docutils literal notranslate"><span class="pre">SERVER_HOST</span></code>.</p> </div> <div class="section" id="refine-configuration-parameters"> <span id="id6"></span><h4><a class="toc-backref" href="#what-s-in-this-document">Refine Configuration Parameters</a><a class="headerlink" href="#refine-configuration-parameters" title="Permalink to this headline">¶</a></h4> <p>You can assign configuration parameters in three ways:</p> <ul class="simple"> <li>Edit the configuration file.</li> <li>Set corresponding environment variables. E.g. the property <code class="docutils literal notranslate"><span class="pre">server.host</span></code> should be written as <code class="docutils literal notranslate"><span class="pre">SERVER_HOST</span></code>.</li> <li>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:</li> </ul> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ontorefine -Dontorefine.config.path<span class="o">=</span><your-config-file> -Dserver.port<span class="o">=</span><your-port> -Xmx4g </pre></div> </div> <p>If the same parameter is set in multiple locations, the following order of precedence applies: <code class="docutils literal notranslate"><span class="pre">config</span> <span class="pre">file</span> <span class="pre"><</span> <span class="pre">environment</span> <span class="pre">variables</span> <span class="pre"><</span> <span class="pre">command-line</span> <span class="pre">arguments</span></code>.</p> <p>Refine takes the following configuration parameters:</p> <ul> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">ontorefine.config.path</span></code>: Location of Refine config file. Created on first startup of Native Refine. Can be changed using the Java command-line property <code class="docutils literal notranslate"><span class="pre">ontorefine.config.path</span></code> or environment variable <code class="docutils literal notranslate"><span class="pre">ONTOREFINE_CONFIG_PATH</span></code>, but not within the config file itself. Defaults:</p> <ul class="simple"> <li>On Mac: <code class="docutils literal notranslate"><span class="pre">{user.home}/.ontorefine/ontorefine.properties</span></code></li> <li>On Windows: <code class="docutils literal notranslate"><span class="pre">\\Users\\<username>\\AppData\\Roaming\OntoRefine\ontorefine.properties</span></code></li> <li>On Linux: <code class="docutils literal notranslate"><span class="pre">{user.home}/.ontorefine/ontorefine.properties</span></code></li> </ul> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">ontorefine.data</span></code>: Location of Refine data (project files and <code class="docutils literal notranslate"><span class="pre">workspace.json</span></code>). Defaults:</p> <ul class="simple"> <li>On Mac: <code class="docutils literal notranslate"><span class="pre">{user.home}/.ontorefine</span></code></li> <li>On Windows: <code class="docutils literal notranslate"><span class="pre">\\Users\\<username>\\AppData\\Roaming\OntoRefine\\refine</span></code></li> <li>On Linux: <code class="docutils literal notranslate"><span class="pre">{user.home}/.ontorefine</span></code></li> </ul> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">ontorefine.dist</span></code>: Refine installation directory. Can be set during installation of Native Refine. Should not be edited, unless Refine is moved manually. Defaults:</p> <ul class="simple"> <li>On Mac: <code class="docutils literal notranslate"><span class="pre">/Applications/Ontotext</span> <span class="pre">Refine.app/Contents/app</span></code></li> <li>On Windows: <code class="docutils literal notranslate"><span class="pre">\\Users\\<username>\\AppData\\Local\\Ontotext</span> <span class="pre">Refine\\app</span></code></li> <li>On Linux: <code class="docutils literal notranslate"><span class="pre">/opt/ontorefine/lib/app/</span></code></li> </ul> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">server.host</span></code>: server on which Refine runs. Useful for CORS configurations. Default: your machine’s hostname</p> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">server.port</span></code>: port on which the Refine server responds. Default: <code class="docutils literal notranslate"><span class="pre">7333</span></code></p> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">graphdb.address</span></code>: URL address of the GraphDB instance that Refine asks for namespaces and class/property autocompletion. Default in the <cite>Setup</cite> menu of the web app: <code class="docutils literal notranslate"><span class="pre">http://localhost:7200</span></code></p> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">graphdb.repository</span></code>: ID of the GraphDB repository that Refine works with. Default in the <cite>Setup</cite> menu of the web app: <code class="docutils literal notranslate"><span class="pre">refine</span></code></p> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">graphdb.auth.method</span></code>: Authentication method used for GraphDB <a class="reference external" href="https://graphdb.ontotext.com/documentation/10.0/access-control.html">Access Control</a>. Case-insensitive. Default: <code class="docutils literal notranslate"><span class="pre">NONE</span></code>. Possible settings:</p> <ul> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">NONE</span></code>: used only when GraphDB security is OFF. This should only be used on a local network not connected to the internet.</p> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">BASIC</span></code>: the username and password are sent in a header as plain text (see <a class="reference external" href="https://graphdb.ontotext.com/documentation/10.0/access-control.html#basic-authentication">Basic authentication</a>). Sending the password as plain text is insecure, so it is important to use <a class="reference external" href="https://graphdb.ontotext.com/documentation/10.0/encryption.html#encryption-in-transit">Encryption in Transit</a> (i.e. <code class="docutils literal notranslate"><span class="pre">https</span></code>) to improve security.</p> <blockquote> <div><ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">graphdb.auth.basic.username</span></code>: username for Basic authentication.</li> <li><code class="docutils literal notranslate"><span class="pre">graphdb.auth.basic.credentials</span></code>: password for Basic authentication.</li> </ul> </div></blockquote> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">GDB</span></code>: token-based authentication, also used by GraphDB Workbench (see <a class="reference external" href="https://graphdb.ontotext.com/documentation/10.0/access-control.html#gdb-authentication">GDB authentication</a>). Refine uses the GraphDB <code class="docutils literal notranslate"><span class="pre">login</span></code> API method to obtain a token: this happens on Refine startup, and whenever the token expires. Token expiration is controlled by the <code class="docutils literal notranslate"><span class="pre">graphdb.auth.token.validity</span></code> parameter in GraphDB (default: 30d). Refine uses the following parameters to perform GraphDB <code class="docutils literal notranslate"><span class="pre">login</span></code>:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">graphdb.auth.gdb.username</span></code>: username for GDB authentication.</li> <li><code class="docutils literal notranslate"><span class="pre">graphdb.auth.gdb.credentials</span></code>: password for GDB authentication.</li> </ul> </li> </ul> </li> </ul> <div class="admonition important"> <p class="first admonition-title">Important</p> <p class="last">You can also connect a GraphDB instance using the visual dialog in Refine’s “Setup” section.</p> </div> <img alt="_images/install-connect-gdb.png" src="_images/install-connect-gdb.png" /> </div> <div class="section" id="jvm-configuration"> <span id="id7"></span><h4><a class="toc-backref" href="#what-s-in-this-document">JVM Configuration</a><a class="headerlink" href="#jvm-configuration" title="Permalink to this headline">¶</a></h4> <p>You can use the following environment variables to control Java startup parameters:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_JAVA_OPTS</span></code>: Sets additional Java parameters (-D or -X)</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_JAVA_32BIT</span></code>: If set to true, configures Refine to run on 32bit Java</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_MIN_MEM</span></code>: Sets the Java minimum heap size (<code class="docutils literal notranslate"><span class="pre">-Xms</span></code> option).</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_MAX_MEM</span></code>: Sets the Java maximum heap size (<code class="docutils literal notranslate"><span class="pre">-Xmx</span></code> option).</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_HEAP_SIZE</span></code>: Sets the Java minimum and maximum heap size (<code class="docutils literal notranslate"><span class="pre">-Xms</span></code> and <code class="docutils literal notranslate"><span class="pre">-Xmx</span></code> option).</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_HEAP_NEWSIZE</span></code>: Sets the initial and maximum heap size for the young generation (<code class="docutils literal notranslate"><span class="pre">-Xmn</span></code> option).</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_GC_LOG</span></code>: If set to true, enables the logging of Java garbage collection.</li> <li><code class="docutils literal notranslate"><span class="pre">ONTOREFINE_GC_LOG_FILE</span></code>: Specifies a custom file for logging of Java garbage collection.</li> </ul> <p>Other Java options are defined at the end of the file <code class="docutils literal notranslate"><span class="pre">{ontorefine.dist}/Ontotext</span> <span class="pre">Refine.cfg</span></code>. Each <code class="docutils literal notranslate"><span class="pre">java-options=</span></code> line provides a single argument passed to the JVM when it starts (<code class="docutils literal notranslate"><span class="pre">-cp</span></code> means “class path”).</p> <p>Here are the options with their default settings on Windows:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>[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 </pre></div> </div> <p>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.</p> <p>For example, if you want to run Refine with 8 Gb of maximum heap memory, you can set the following option:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">java</span><span class="o">-</span><span class="n">options</span><span class="o">=-</span><span class="n">Xmx8g</span> </pre></div> </div> <p>The launcher spawns the Refine application within the same JVM that it operates in, so you cannot change JVM options from the command line.</p> </div> </div> </div> <div class="section" id="migrating-existing-projects-from-graphdb-9"> <h2><a class="toc-backref" href="#what-s-in-this-document">Migrating Existing Projects from GraphDB 9</a><a class="headerlink" href="#migrating-existing-projects-from-graphdb-9" title="Permalink to this headline">¶</a></h2> <p>Migrating projects from existing GraphDB instances to Refine is possible in bulk or manually.</p> <div class="section" id="manual-migration"> <h3><a class="toc-backref" href="#what-s-in-this-document">Manual Migration</a><a class="headerlink" href="#manual-migration" title="Permalink to this headline">¶</a></h3> <p>You can use manual migration for a small number of projects:</p> <ul class="simple"> <li>Export the projects one by one from GraphDB 9 using the “Export project” function</li> <li>Import the projects one by one to Refine 1.0 using the “Import project” function</li> </ul> </div> <div class="section" id="bulk-migration"> <h3><a class="toc-backref" href="#what-s-in-this-document">Bulk Migration</a><a class="headerlink" href="#bulk-migration" title="Permalink to this headline">¶</a></h3> <p>Bulk Migration migrates all projects from a Refine workspace at once.</p> <ul> <li><p class="first">Make sure that the old OntoRefine (part of GraphDB 9) is not being used</p> </li> <li><p class="first">There are several ways in which you can transfer the workspace (set of projects):</p> <ol class="arabic simple"> <li>Set the <code class="docutils literal notranslate"><span class="pre">{ontorefine.data}</span></code> configuration parameter (of the new Refine) to point to the old data folder</li> <li>Replace the entire contents of the new (Refine) data folder with the contents of the old data folder</li> <li>Move project subfolders from the old data folder to the new data folder. (If a project ID already exists in the new data folder, leave it alone). Then edit the <code class="docutils literal notranslate"><span class="pre">projectIDs</span></code> array in <code class="docutils literal notranslate"><span class="pre">workspace.json</span></code> to list all projects.</li> </ol> <blockquote> <div><ul class="simple"> <li>This alternative is for advanced users only</li> <li>Make sure you keep a backup of the old and new workspace folders</li> </ul> </div></blockquote> </li> <li><p class="first">Restart Refine in order to reload the projects</p> </li> </ul> </div> </div> </div> </div> </div> <hr class="m-0"> <footer class="main-container py-5"> <div class="container-fluid"> <div class="row"> <div class="col-12 col-sm-6 col-lg-4"> <h4>Download documentation</h4>  <ul class="list-inline"> <li class="list-inline-item"> <a href="/ontorefine/1.2/pdf/Refine.pdf" download class="btn btn-link text-secondary px-0" target="_blank"><span class="icon-download text-tertiary"></span> PDF</a> </li> <li class="list-inline-item"> <a href="/ontorefine/1.2/epub/Refine.epub" download class="btn btn-link text-secondary px-0" target="_blank"><span class="icon-download text-tertiary"></span> ePUB</a> </li> </ul> </div> <div class="col-12 col-sm-6 col-lg-4"> <h4>Contacts</h4> <ul class="list-unstyled mb-4"> <li class="m-0"> <a href="mailto:refine-support@ontotext.com" class="btn btn-link text-secondary px-0" target="_blank"> <span class="icon-email text-tertiary"></span> <b>Support</b> <span class="hidden-lg-down">· refine-support@ontotext.com</span> </a> </li> <li class="m-0"> <a href="mailto:sales@ontotext.com" class="btn btn-link text-secondary px-0" target="_blank"> <span class="icon-email text-tertiary"></span> <b>Sales</b> <span class="hidden-lg-down">· sales@ontotext.com</span> </a> </li> <li class="m-0 mb-3"> <a href="mailto:info@ontotext.com" class="btn btn-link text-secondary px-0" target="_blank"> <span class="icon-email text-tertiary"></span> <b>General</b> <span class="hidden-lg-down">· info@ontotext.com</span> </a> </li> <li class="m-0"><span href="mailto:info@ontotext.com" class="btn btn-link text-secondary px-0"><span class="icon-phone text-tertiary"></span> <b>US (toll free)</b> · 1-866-972-6686</span></li> <li class="m-0"><span href="mailto:info@ontotext.com" class="btn btn-link text-secondary px-0"><span class="icon-phone text-tertiary"></span> <b>Europe</b> · +359 2 974 61 60</span></li> </ul> </div> <div class="col-12 col-sm-6 col-lg-4 mb-4"> <h4>More info</h4> <ul class="list-unstyled mb-4"> <li class="m-0"><a href="https://www.ontotext.com/company/" class="btn btn-link text-secondary px-0" target="_blank"><span class="icon-external text-tertiary"></span> About Ontotext</a></li> <li class="m-0"><a href="https://www.w3.org/standards/semanticweb/" class="btn btn-link text-secondary px-0" target="_blank"><span class="icon-external text-tertiary"></span> Semantic web</a></li> </ul> <h4>Follow us</h4> <div class="mb-4"> <a data-toggle="tooltip" title="" href="https://www.linkedin.com/company/ontotext-ad" class="btn btn-link px-0" target="_blank" data-original-title="LinkedIn"><span class="icon-linkedin icon-lg text-linkedin"></span></a> <a data-toggle="tooltip" title="" href="https://twitter.com/ontotext" class="btn btn-link px-0" target="_blank" data-original-title="Twitter"><span class="icon-twitter icon-lg text-twitter"></span></a> <a data-toggle="tooltip" title="" href="https://www.facebook.com/Ontotext" class="btn btn-link px-0" target="_blank" data-original-title="Facebook"><span class="icon-facebook icon-lg text-facebook"></span></a> <a data-toggle="tooltip" title="" href="https://www.youtube.com/ontotext" class="btn btn-link px-0" target="_blank" data-original-title="Youtube"><span class="icon-youtube icon-lg text-youtube"></span></a>  </div> </div> </div>  <div class="text-muted small d-flex align-items-center"> <div> <a href="https://ontotext.com/" target="_blank" class="d-inline-block mb-3 mb-md-0 mr-2"><img src="_static/ot-logo.svg" class="m-0" height="26" alt="Ontotext logo"></a> <br class="hidden-md-up"> © Copyright 2022, Ontotext. Last updated on 19 June, 2023. | <a href="https://ontotext.com/privacy-policy-2/">Privacy</a> </div> <div class="ml-auto"> <button id="scrollToTop" class="btn btn-link" data-toggle="tooltip" data-placement="top" title="" data-original-title="Back to top"><span class="icon-arrow-up icon-2x"></span></button> </div> </div> </div> </footer> </div> </body> </html>