| <!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta http-equiv=x-ua-compatible content="ie=edge"><meta name=lang:clipboard.copy content="Copy to clipboard"><meta name=lang:clipboard.copied content="Copied to clipboard"><meta name=lang:search.language content=en><meta name=lang:search.pipeline.stopwords content=True><meta name=lang:search.pipeline.trimmer content=True><meta name=lang:search.result.none content="No matching documents"><meta name=lang:search.result.one content="1 matching document"><meta name=lang:search.result.other content="# matching documents"><meta name=lang:search.tokenizer content=[\s\-]+><link rel="shortcut icon" href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.0.4, mkdocs-material-4.4.2"><title>Deployment - Eclipse Hawk</title><link rel=stylesheet href=../../assets/stylesheets/application.30686662.css><link rel=stylesheet href=../../assets/stylesheets/application-palette.a8b3c06d.css><meta name=theme-color content=#7e57c2><script src=../../assets/javascripts/modernizr.74668098.js></script><link href=https://fonts.gstatic.com rel=preconnect crossorigin><link rel=stylesheet href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono&display=fallback"><style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style><link rel=stylesheet href=../../assets/fonts/material-icons.css><link rel=stylesheet href=../../stylesheets/extra.css><!-- FAVICON --><link rel=apple-touch-icon sizes=180x180 href=/img/apple-touch-icon.png><link rel=icon type=image/png sizes=32x32 href=/img/favicon-32x32.png><link rel=icon type=image/png sizes=16x16 href=/img/favicon-16x16.png><link rel=manifest href=/img/site.webmanifest><link rel=mask-icon href=/img/safari-pinned-tab.svg color=#5bbad5><link rel="shortcut icon" href=/img/favicon.ico><meta name=msapplication-TileColor content=#b91d47><meta name=msapplication-config content=/img/browserconfig.xml><meta name=theme-color content=#ffffff></head> <body dir=ltr data-md-color-primary=deep-purple data-md-color-accent=deep-purple> <svg class=md-svg> <defs> </defs> </svg> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay data-md-component=overlay for=__drawer></label> <a href=#initial-setup tabindex=1 class=md-skip> Skip to content </a> <header class=md-header data-md-component=header> <nav class="md-header-nav md-grid"> <div class=md-flex> <div class="md-flex__cell md-flex__cell--shrink"> <a href=../.. title="Eclipse Hawk" class="md-header-nav__button md-logo"> <img src=../../img/hawk-logo-white.svg width=24 height=24> </a> </div> <div class="md-flex__cell md-flex__cell--shrink"> <label class="md-icon md-icon--menu md-header-nav__button" for=__drawer></label> </div> <div class="md-flex__cell md-flex__cell--stretch"> <div class="md-flex__ellipsis md-header-nav__title" data-md-component=title> <span class=md-header-nav__topic> Eclipse Hawk </span> <span class=md-header-nav__topic> Deployment </span> </div> </div> <div class="md-flex__cell md-flex__cell--shrink"> <label class="md-icon md-icon--search md-header-nav__button" for=__search></label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query placeholder=Search autocapitalize=off autocorrect=off autocomplete=off spellcheck=false data-md-component=query data-md-state=active> <label class="md-icon md-search__icon" for=__search></label> <button type=reset class="md-icon md-search__icon" data-md-component=reset tabindex=-1>  </button> </form> <div class=md-search__output> <div class=md-search__scrollwrap data-md-scrollfix> <div class=md-search-result data-md-component=result> <div class=md-search-result__meta> Type to start searching </div> <ol class=md-search-result__list></ol> </div> </div> </div> </div> </div> </div> <div class="md-flex__cell md-flex__cell--shrink"> <div class=md-header-nav__source> <a href=https://git.eclipse.org/c/hawk/hawk.git/ title="Go to repository" class=md-source data-md-source> <div class=md-source__repository> Git repository @ Eclipse </div> </a> </div> </div> </div> </nav> </header> <div class=md-container> <main class=md-main role=main> <div class="md-main__inner md-grid" data-md-component=container> <div class="md-sidebar md-sidebar--primary" data-md-component=navigation> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--primary" data-md-level=0> <label class="md-nav__title md-nav__title--site" for=__drawer> <a href=../.. title="Eclipse Hawk" class="md-nav__button md-logo"> <img src=../../img/hawk-logo-white.svg width=48 height=48> </a> Eclipse Hawk </label> <div class=md-nav__source> <a href=https://git.eclipse.org/c/hawk/hawk.git/ title="Go to repository" class=md-source data-md-source> <div class=md-source__repository> Git repository @ Eclipse </div> </a> </div> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../.. title=Home class=md-nav__link> Home </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle=nav-2 type=checkbox id=nav-2> <label class=md-nav__link for=nav-2> Basic use </label> <nav class=md-nav data-md-component=collapsible data-md-level=1> <label class=md-nav__title for=nav-2> Basic use </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../basic-use/installation/ title=Installation class=md-nav__link> Installation </a> </li> <li class=md-nav__item> <a href=../../basic-use/core-concepts/ title="Core concepts" class=md-nav__link> Core concepts </a> </li> <li class=md-nav__item> <a href=../../basic-use/examples-xmi/ title="Examples (XMI)" class=md-nav__link> Examples (XMI) </a> </li> <li class=md-nav__item> <a href=../../basic-use/examples-modelio/ title="Examples (Modelio)" class=md-nav__link> Examples (Modelio) </a> </li> <li class=md-nav__item> <a href=../../basic-use/papyrus/ title="Papyrus UML support" class=md-nav__link> Papyrus UML support </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle=nav-3 type=checkbox id=nav-3> <label class=md-nav__link for=nav-3> Advanced use </label> <nav class=md-nav data-md-component=collapsible data-md-level=1> <label class=md-nav__title for=nav-3> Advanced use </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../advanced-use/graph-as-emf/ title="Graph as EMF model" class=md-nav__link> Graph as EMF model </a> </li> <li class=md-nav__item> <a href=../../advanced-use/advanced-props/ title="Advanced properties" class=md-nav__link> Advanced properties </a> </li> <li class=md-nav__item> <a href=../../advanced-use/meta-queries/ title="Meta-level queries" class=md-nav__link> Meta-level queries </a> </li> <li class=md-nav__item> <a href=../../advanced-use/temporal-queries/ title="Temporal queries" class=md-nav__link> Temporal queries </a> </li> <li class=md-nav__item> <a href=../../advanced-use/oomph/ title="Oomph and Hawk" class=md-nav__link> Oomph and Hawk </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle=nav-4 type=checkbox id=nav-4 checked> <label class=md-nav__link for=nav-4> Server </label> <nav class=md-nav data-md-component=collapsible data-md-level=1> <label class=md-nav__title for=nav-4> Server </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../architecture/ title=Architecture class=md-nav__link> Architecture </a> </li> <li class=md-nav__item> <a href=../api/ title="Thrift API" class=md-nav__link> Thrift API </a> </li> <li class=md-nav__item> <a href=../api-security/ title="Thrift API security" class=md-nav__link> Thrift API security </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-toggle md-nav__toggle" data-md-toggle=toc type=checkbox id=__toc> <label class="md-nav__link md-nav__link--active" for=__toc> Deployment </label> <a href=./ title=Deployment class="md-nav__link md-nav__link--active"> Deployment </a> <nav class="md-nav md-nav--secondary"> <label class=md-nav__title for=__toc>Table of contents</label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=#initial-setup class=md-nav__link> Initial setup </a> </li> <li class=md-nav__item> <a href=#ini-options class=md-nav__link> .ini options </a> </li> <li class=md-nav__item> <a href=#concerns-for-production-environments class=md-nav__link> Concerns for production environments </a> </li> <li class=md-nav__item> <a href=#secure-storage-of-vcs-credentials class=md-nav__link> Secure storage of VCS credentials </a> </li> <li class=md-nav__item> <a href=#setting-up-ssl-certificates-for-the-server class=md-nav__link> Setting up SSL certificates for the server </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../cli/ title="Console client" class=md-nav__link> Console client </a> </li> <li class=md-nav__item> <a href=../eclipse/ title="Eclipse client" class=md-nav__link> Eclipse client </a> </li> <li class=md-nav__item> <a href=../file-config/ title="File-based configuration" class=md-nav__link> File-based configuration </a> </li> <li class=md-nav__item> <a href=../logging/ title=Logging class=md-nav__link> Logging </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-toggle md-nav__toggle" data-md-toggle=nav-5 type=checkbox id=nav-5> <label class=md-nav__link for=nav-5> Developers </label> <nav class=md-nav data-md-component=collapsible data-md-level=1> <label class=md-nav__title for=nav-5> Developers </label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=../../developers/run-from-source/ title="Run GUI from source" class=md-nav__link> Run GUI from source </a> </li> <li class=md-nav__item> <a href=../../developers/server-from-source/ title="Run Server from source" class=md-nav__link> Run Server from source </a> </li> <li class=md-nav__item> <a href=../../developers/plain-maven/ title="Build with plain Maven" class=md-nav__link> Build with plain Maven </a> </li> <li class=md-nav__item> <a href=../../developers/website/ title="Work on the website" class=md-nav__link> Work on the website </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../../additional-resources/ title="Additional resources" class=md-nav__link> Additional resources </a> </li> <li class=md-nav__item> <a href=https://www.eclipse.org/forums/index.php/f/442/ title=Forum class=md-nav__link> Forum </a> </li> <li class=md-nav__item> <a href=https://ci.eclipse.org/hawk/ title=Builds class=md-nav__link> Builds </a> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component=toc> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--secondary"> <label class=md-nav__title for=__toc>Table of contents</label> <ul class=md-nav__list data-md-scrollfix> <li class=md-nav__item> <a href=#initial-setup class=md-nav__link> Initial setup </a> </li> <li class=md-nav__item> <a href=#ini-options class=md-nav__link> .ini options </a> </li> <li class=md-nav__item> <a href=#concerns-for-production-environments class=md-nav__link> Concerns for production environments </a> </li> <li class=md-nav__item> <a href=#secure-storage-of-vcs-credentials class=md-nav__link> Secure storage of VCS credentials </a> </li> <li class=md-nav__item> <a href=#setting-up-ssl-certificates-for-the-server class=md-nav__link> Setting up SSL certificates for the server </a> </li> </ul> </nav> </div> </div> </div> <div class=md-content> <article class="md-content__inner md-typeset"> <h1>Deployment</h1> <h2 id=initial-setup>Initial setup<a class=headerlink href=#initial-setup title="Permanent link">¶</a></h2> <p>To run the Hawk server, download the latest <code>hawk-server-*.zip</code> file for your operating system and architecture of choice from the <a href=https://github.com/mondo-project/mondo-hawk/releases>"Releases" section on Github</a>, and unpack it. Note that <code>-nogpl-</code> releases do not include GPL-licensed components: if you want them in your server, you will have to build it yourself.</p> <p>Make any relevant changes to the <code>mondo-server.ini</code> file, and then run the <code>run-server.sh</code> script from Linux, or simply the provided <code>mondo-server</code> binary from Mac or Windows.</p> <p>If everything goes well, you should see this message:</p> <div class=codehilite><pre><span></span>Welcome to the Hawk Server! |
| List available commands with 'hserverHelp'. |
| Stop the server with 'shutdown' and then 'close'. |
| |
| osgi> |
| </pre></div> <p>You may now use the Thrift APIs as normal. If you need to make any tweaks, continue reading!</p> <h2 id=ini-options>.ini options<a class=headerlink href=#ini-options title="Permanent link">¶</a></h2> <p>You will notice that the <code>.ini</code> file has quite a few different options defined, in addition to the JVM options defined with <code>-vmargs</code>. We will analyze them in this section.</p> <ul> <li><code>-console</code> allows us to use the OSGi console to manage Hawk instances.</li> <li><code>-consoleLog</code> plugs Eclipse logging into the console, for following what is going with the server.</li> <li><code>-Dartemis.security.enabled=false</code> disables the Shiro security realm for the embedded Artemis server. Production environments should set this to <code>true</code>.</li> <li><code>-Dhawk.artemis.host=localhost</code> has Artemis listening only on 127.0.0.1. You should change this to the IP address or hostname of the network interface that you want Artemis to listen on. </li> <li><code>-Dhawk.artemis.listenAll=false</code> prevents Artemis from listening on all addresses. You can set this to <code>true</code> and ignore <code>hawk.artemis.host</code>.</li> <li><code>-Dhawk.artemis.sslEnabled=false</code> disables HTTPS on Artemis. If you enable SSL, you will need to check the "Enabling HTTPS" section further below!</li> <li><code>-Dhawk.tcp.port=2080</code> enables the TCP server for only the Hawk API, and not the Users management one. This API is unsecured, so do this at your own risk. For production environments, you should remove this line.</li> <li><code>-Dhawk.tcp.thriftProtocol=TUPLE</code> changes the Thrift protocol (encoding) that should be used for the TCP endpoint.</li> <li><code>-Dorg.eclipse.equinox.http.jetty.customizer.class=org.hawk.service.server.gzip.Customizer</code> is needed for the * <code>-Dorg.osgi.service.http.port=8080</code> sets the HTTP port for the APIs to 8080.</li> <li><code>-Dorg.osgi.service.http.port.secure=8443</code> sets the HTTPS port for the APIs to 8443.</li> <li><code>-Dosgi.noShutdown=true</code> is needed for the server to stay running.</li> <li><code>-Dsvnkit.library.gnome-keyring.enabled=false</code> is required to work around a bug in the integration of the GNOME keyring in recent Eclipse releases.</li> <li><code>-eclipse.keyring</code> and <code>-eclipse.password</code> are the paths to the keyring and keyring password files which store the VCS credentials Hawk needs to access password-protected SVN repositories. (For Git repositories, you are assumed to keep your own clone and do any periodic pulling yourself.)</li> <li><code>-XX:+UseG1GC</code> (part of <code>-vmargs</code>) improves garbage collection in OrientDB and Neo4j.</li> <li><code>-XX:+UseStringDeduplication</code> (part of <code>-vmargs</code> as well) noticeably reduces memory use in OrientDB.</li> </ul> <h2 id=concerns-for-production-environments>Concerns for production environments<a class=headerlink href=#concerns-for-production-environments title="Permanent link">¶</a></h2> <p>One important detail for production environments is turning on security. This is disabled by default to help with testing and initial evaluations, but it can be enabled by running the server once, shutting it down and then editing the <code>shiro.ini</code> file appropriately (relevant sections include comments on what to do) and switching <code>artemis.security.enabled</code> to <code>true</code> in the <code>mondo-server.ini</code> file. The MONDO server uses an embedded MapDB database, which is managed through the Users [[Thrift API]]. Once security is enabled, all Thrift APIs and all external (not in-VM) Artemis connections become password-protected.</p> <p>If you enable security, you will want to ensure that <code>-Dhawk.tcp.port</code> is not present in the <code>mondo-server.ini</code> file, since the Hawk TCP port does not support security for the sake of raw performance.</p> <p>If you are deploying this across a network, you will need to edit the <code>mondo-server.ini</code> file and customize the <code>hawk.artemis.host</code> line to the host that you want the Artemis server to listen to. This should be the IP address or hostname of the MONDO server in the network, normally. The Thrift API uses this hostname as well in its replies to the <code>watchModelChanges</code> operation in the Hawk API.</p> <p>Additionally, if the server IP is dynamic but has a consistent DNS name (e.g. an Amazon VM + a dynamic DNS provider), we recommend setting <code>hawk.artemis.listenAll</code> to <code>true</code> (so the Artemis server will keep listening on all interfaces, even if the IP address changes) and using the DNS name for <code>hawk.artemis.host</code> instead of a literal IP address.</p> <p>Finally, production environments should enable and enforce SSL as well, since plain HTTP is insecure. The Linux products include a shell script that generates simple self-signed key/trust stores and indicates which Java system properties should be set on the server and the client.</p> <h2 id=secure-storage-of-vcs-credentials>Secure storage of VCS credentials<a class=headerlink href=#secure-storage-of-vcs-credentials title="Permanent link">¶</a></h2> <p>The server hosts a copy of the Hawk model indexer, which may need to access remote Git and Subversion repositories. To access password-protected repositories, the server will need to store the proper credentials in a secure way that will not expose them to other users in the same machine. To achieve this goal, the MONDO server uses the Eclipse secure storage facilities to save the password in an encrypted form. Users need to prepare the secure storage by following these two steps:</p> <ol> <li> <p>The secure store must be placed in a place no other program will try to access concurrently. This can be done by editing the <code>mondo-server.ini</code> server configuration file and adding this: <code>-eclipse.keyring /path/to/keyringfile</code> That path should be only readable by the user running the server, for added security.</p> </li> <li> <p>An encryption password must be set. For Windows and Mac, the available OS integration should be enough. For Linux environments, two lines have to be added at the beginning of the <code>mondo-server.ini</code> file, specifying the path to a password file with: <code>-eclipse.password /path/to/passwordfile.</code> On Linux, creating a password file from 100 bytes of random data that is only readable by the current user can be done with these commands: <code>$ head -c 100 /dev/random | base64 > /path/to/password $ chmod 400 /path/to/password</code></p> </li> </ol> <p>The server tests on startup that the secure store has been set properly, warning users if encryption is not available and urging them to revise their setup.</p> <h2 id=setting-up-ssl-certificates-for-the-server>Setting up SSL certificates for the server<a class=headerlink href=#setting-up-ssl-certificates-for-the-server title="Permanent link">¶</a></h2> <p>SSL is handled through standard Java keystore (<code>.jks</code>) files. To produce a keystore with some self-signed certificates, you could use the <code>generate-ssl-certs.sh</code> script included in the Linux distribution, or run these commands from other operating systems (replace CN, OU and so forth with the appropriate values):</p> <div class=codehilite><pre><span></span>keytool -genkey -keystore mondo-server-keystore.jks -storepass secureexample -keypass secureexample -dname "CN=localhost, OU=Artemis, O=ActiveMQ, L=AMQ, S=AMQ, C=AMQ" -keyalg RSA |
| keytool -export -keystore mondo-server-keystore.jks -file mondo-jks.cer -storepass secureexample |
| keytool -import -keystore mondo-client-truststore.jks -file mondo-jks.cer -storepass secureexample -keypass secureexample -noprompt |
| </pre></div> <p>Once you have your .jks, on the client .ini you'll need to set:</p> <div class=codehilite><pre><span></span>-Djavax.net.ssl.trustStore=path/to/client-truststore.jks |
| -Djavax.net.ssl.trustStorePassword=secureexample |
| </pre></div> <p>On the server .ini, you'll need to enable SSL and tell Jetty and Artemis about your KeyStore:</p> <div class=codehilite><pre><span></span>-Dorg.eclipse.equinox.http.jetty.https.enabled=true |
| -Dhawk.artemis.sslEnabled=true |
| -Dorg.eclipse.equinox.http.jetty.ssl.keystore=path/to/server-keystore.jks |
| -Djavax.net.ssl.keyStore=path/to/server-keystore.jks |
| </pre></div> <p>You'll be prompted for the key store password three times: two by Jetty and once by the Artemis server. If you don't want these prompts, you could use these properties, but using them is <em>UNSAFE</em>, as another user in the same machine could retrieve these passwords from your process manager:</p> <div class=codehilite><pre><span></span>-Djavax.net.ssl.keyStorePassword=secureexample |
| -Dorg.eclipse.equinox.http.jetty.ssl.keypassword=secureexample |
| -Dorg.eclipse.equinox.http.jetty.ssl.password=secureexample |
| </pre></div> </article> </div> </div> </main> <footer class=md-footer> <div class=md-footer-nav> <nav class="md-footer-nav__inner md-grid"> <a href=../api-security/ title="Thrift API security" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel=prev> <div class="md-flex__cell md-flex__cell--shrink"> <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i> </div> <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"> <span class=md-flex__ellipsis> <span class=md-footer-nav__direction> Previous </span> Thrift API security </span> </div> </a> <a href=../cli/ title="Console client" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel=next> <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title"> <span class=md-flex__ellipsis> <span class=md-footer-nav__direction> Next </span> Console client </span> </div> <div class="md-flex__cell md-flex__cell--shrink"> <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i> </div> </a> </nav> </div> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-footer-copyright> <div class=md-footer-copyright__highlight> Copyright © Eclipse Foundation, Inc. All Rights Reserved. </div> powered by <a href=https://www.mkdocs.org>MkDocs</a> and <a href=https://squidfunk.github.io/mkdocs-material/ > Material for MkDocs</a> </div> <div class="md-footer-copyright hawk-eclipse-links"> <ul> <li><a href=https://www.eclipse.org/legal/privacy.php>Privacy Policy</a></li> <li><a href=https://www.eclipse.org/legal/termsofuse.php>Terms of Use</a></li> <li><a href=https://www.eclipse.org/legal/copyright.php>Copyright Agent</a></li> </ul> </div> </div> </div> </footer> </div> <script src=../../assets/javascripts/application.c648116f.js></script> <script>app.initialize({version:"1.0.4",url:{base:"../.."}})</script> </body> </html> |
