docs/1.3.0/developer-guide/running.html - www.eclipse.org/kapua - Git at Google


 <!DOCTYPE HTML>
 <html lang="" >
     <head>
         <meta charset="UTF-8">
         <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
         <title>Running · Eclipse Kapua™ Developer Guide</title>
         <meta http-equiv="X-UA-Compatible" content="IE=edge" />
         <meta name="description" content="">
         <meta name="generator" content="GitBook 3.2.2">


     <link rel="stylesheet" href="gitbook/style.css">


                 <link rel="stylesheet" href="gitbook/gitbook-plugin-hints/plugin-hints.css">


                 <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">


                 <link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">


                 <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">


     <meta name="HandheldFriendly" content="true"/>
     <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
     <meta name="apple-mobile-web-app-capable" content="yes">
     <meta name="apple-mobile-web-app-status-bar-style" content="black">
     <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
     <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">


     <link rel="next" href="running.html" />


     <link rel="prev" href="building.html" />


     </head>
     <body>

 <div class="book">
     <div class="book-summary">


 <div id="book-search-input" role="search">
     <input type="text" placeholder="Type to search" />
 </div>


                 <nav role="navigation">


 <ul class="summary">


         <li class="chapter " data-level="1.1" data-path="./">

                 <a href="./">


                     Introduction

                 </a>


         </li>

         <li class="chapter " data-level="1.2" data-path="building.html">

                 <a href="building.html">


                     Building

                 </a>


             <ul class="articles">


         <li class="chapter " data-level="1.2.1" data-path="building.html">

                 <a href="building.html#kapua">


                     Kapua

                 </a>


         </li>

         <li class="chapter " data-level="1.2.2" data-path="building.html">

                 <a href="building.html#documentation">


                     Documentation

                 </a>


         </li>


             </ul>

         </li>

         <li class="chapter active" data-level="1.3" data-path="running.html">

                 <a href="running.html">


                     Running

                 </a>


             <ul class="articles">


         <li class="chapter " data-level="1.3.1" data-path="running.html">

                 <a href="running.html#docker-containers">


                     Docker

                 </a>


         </li>

         <li class="chapter " data-level="1.3.2" data-path="running.html">

                 <a href="running.html#openshift">


                     OpenShift

                 </a>


         </li>

         <li class="chapter " data-level="1.3.3" data-path="running.html">

                 <a href="running.html#vagrant">


                     Vagrant

                 </a>


         </li>


             </ul>

         </li>

         <li class="chapter " data-level="1.4" data-path="ide.html">

                 <a href="ide.html">


                     Setting up an IDE

                 </a>


             <ul class="articles">


         <li class="chapter " data-level="1.4.1" data-path="ide.html">

                 <a href="ide.html#eclipse">


                     Eclipse IDE

                 </a>


         </li>


             </ul>

         </li>

         <li class="chapter " data-level="1.5" >

                 <span>


                     Configuration

                 </span>


             <ul class="articles">


         <li class="chapter " data-level="1.5.1" data-path="sso.html">

                 <a href="sso.html">


                     Single sign-on

                 </a>


         </li>


             </ul>

         </li>

         <li class="chapter " data-level="1.6" data-path="database.html">

                 <a href="database.html">


                     Working with database

                 </a>


         </li>

         <li class="chapter " data-level="1.7" data-path="client.html">

                 <a href="client.html">


                     Client generation

                 </a>


         </li>

         <li class="chapter " data-level="1.8" data-path="qa.html">

                 <a href="qa.html">


                     QA process

                 </a>


         </li>


     <li class="divider"></li>

     <li>
         <a href="https://www.gitbook.com" target="blank" class="gitbook-link">
             Published with GitBook
         </a>
     </li>
 </ul>


                 </nav>


     </div>

     <div class="book-body">

             <div class="body-inner">


 <div class="book-header" role="navigation">


     <!-- Title -->
     <h1>
         <i class="fa fa-circle-o-notch fa-spin"></i>
         <a href="." >Running</a>
     </h1>
 </div>


                     <div class="page-wrapper" tabindex="-1" role="main">
                         <div class="page-inner">

 <div id="book-search-results">
     <div class="search-noresults">

                                 <section class="normal markdown-section">

                                 <h1 id="running">Running</h1>
 <p>Kapua can be run in a few different ways. See the following chapters for
 more information about how to start and run Kapua.</p>
 <p><div class="alert alert-info hints-alert"><div class="hints-icon"><i class="fa fa-info-circle"></i></div><div class="hints-container"><p>Most of the following descriptions focus on a developer centric
 setup and not on a full blown production setup.</p>
 </div></div></p>
 <h2 id="docker-containers">Docker containers</h2>
 <p>Before running Kapua on Docker, you need to </p>
 <ol>
 <li>Install <code>docker</code> and <code>docker-compose</code></li>
 <li>Run <code>mvn -f assembly -Pdocker</code> once to build containers. Run <code>mvn -f assembly -Pconsole,docker</code> if you also need to build the Web Console image.</li>
 </ol>
 <p>Now, you can start Kapua by using Docker Compose. To do so, run</p>
 <pre><code>kapua/deployment/docker/docker-deploy.sh
 </code></pre><p>After Kapua has been started, you can navigate your browser to <a href="http://localhost:8080" target="_blank">http://localhost:8080</a> and log in using the following credentials:
 <code>kapua-sys</code> : <code>kapua-password</code></p>
 <p>You can access the API using: <a href="http://localhost:8081" target="_blank">http://localhost:8081</a></p>
 <p><strong>Note</strong>: If you are using Docker on Windows the hostname will most likely not be <code>localhost</code> but
 the IP address of your docker instance.</p>
 <p>By default, the <code>latest</code> version of images will be used. If you want to run some other version of Kapua, set the <code>IMAGE_VERSION</code> environment variable, like</p>
 <pre><code>export IMAGE_VERSION=0.2.0
 </code></pre><p>To stop Kapua, run</p>
 <pre><code>kapua/deployment/docker/docker-undeploy.sh
 </code></pre><h2 id="openshift">OpenShift</h2>
 <p>OpenShift is a PaaS (Platform As A Service) platform based on Kubernetes. Kapua supports deployments into <a href="https://www.openshift.org" target="_blank">OpenShift Origin</a>,
 which is an open source community project. Origin sources, can be found <a href="https://www.openshift.org/" target="_blank">here</a>. We support Kapua on OpenShift Origin <strong>1.4.1</strong>.</p>
 <p>Currently we support running OpenShift only on Linux OS. If you would like to run Kapua on Mac OS or on Windows for development purposes, please install Linux
 (for example Fedora 25) into a virtual machine (for example VirtualBox) and install OpenShift there.</p>
 <h3 id="starting-openshift-cluster">Starting OpenShift cluster</h3>
 <p>For running Kapua on an OpenShift you need to
 have OpenShift cluster installed and started in the first place. You can install it by yourself or rely on the script we provides:</p>
 <pre><code>sudo kapua/deployment/openshift/openshift-start.sh
 </code></pre><p>If you are running your OpenShift cluster for the first time, execute the following initialized script as well:</p>
 <pre><code>kapua/deployment/openshift/openshift-initialize.sh
 </code></pre><p>Initialization script is responsible for logging you into a cluster and creating new OpenShift project for Kapua.</p>
 <p>If your Openshift cluster is not on the localhost, set the <code>OPENSHIFT_HOST</code> environment variable. For example, something like</p>
 <pre><code>export OPENSHIFT_HOST=192.168.64.2:8443
 </code></pre><p>If for some reasons, you cannot start your cluster, try to execute the startup script with option <code>DOCKERIZED=FALSE</code>:</p>
 <pre><code>sudo DOCKERIZED=FALSE kapua/deployment/openshift/openshift-start.sh
 </code></pre><p>Option <code>DOCKERIZED=FALSE</code> tells startup script to use standard binary installation of OpenShift Origin instead of Docker-based <code>oc cluster up</code> command.</p>
 <h3 id="deploying-kapua-into-openshift-cluster">Deploying Kapua into OpenShift cluster</h3>
 <p>Now when you have OpenShift cluster up, running and initialized, execute the following script:</p>
 <pre><code>cd kapua/deployment/openshift
 ./openshift-deploy.sh
 </code></pre><p>Now open the following URL in your web browser - <code>http://localhost:8080</code>. And log-in into Kapua UI using default
 credentials:</p>
 <dl>
     <dt>username</dt><dd>kapua-sys</dd>
     <dt>password</dt><dd>kapua-password</dd>
 </dl>


 <h2 id="using-minishift">Using Minishift</h2>
 <p>Minishift is a tool that helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM. Follow <a href="https://docs.openshift.org/latest/minishift/getting-started/index.html" target="_blank">this guide</a> for installing and having Minishift up and running.</p>
 <p>Steps to run Kapua on Minishift are the  following</p>
 <ol>
 <li><p>Start Minishift (make sure you have enough memory and cpu resources for your cluster)</p>
 <pre><code class="lang-bash"> minishift start --memory 8GB --cpus 4
 </code></pre>
 </li>
 <li><p>Export Minishift docker and oc tools</p>
 <pre><code class="lang-bash"> <span class="hljs-built_in">eval</span> $(minishift docker-env)
  <span class="hljs-built_in">eval</span> $(minishift oc-env)
 </code></pre>
 </li>
 <li><p>Export address of the cluster</p>
 <pre><code class="lang-bash"> <span class="hljs-built_in">export</span> OPENSHIFT_HOST=$(minishift ip):8443
 </code></pre>
 </li>
 <li><p>Initialize Kapua project</p>
 <pre><code class="lang-bash"> kapua/deployment/openshift/openshift-initialize.sh
 </code></pre>
 </li>
 <li><p>Deploy Kapua components</p>
 <pre><code class="lang-bash"> <span class="hljs-built_in">cd</span> kapua/deployment/openshift
  ./openshift-deploy.sh
 </code></pre>
 </li>
 <li><p>Visit Minishift console</p>
 <pre><code class="lang-bash"> minishift dashboard
 </code></pre>
 </li>
 </ol>
 <h2 id="advanced-openshift-configuration">Advanced OpenShift configuration</h2>
 <h3 id="external-node-port-for-mqtt">External Node port for MQTT</h3>
 <p>The default setup uses port 31883 to export the MQTT over TCP port of the broker. This means that you can connect
 from outside of the OpenShift cluster to Kapua over port 31883 (instead of port 1883) to Kapua.</p>
 <p>However it is only possible for one service to make use of this port. If you are planning to add a second Kapua installation
 and still want to use the external node port, then you will need to choose a different, yet unsed, port.</p>
 <p>Also see: <a href="https://docs.openshift.com/container-platform/latest/dev_guide/getting_traffic_into_cluster.html" target="_blank">https://docs.openshift.com/container-platform/latest/dev_guide/getting_traffic_into_cluster.html</a></p>
 <h3 id="adding-metrics">Adding metrics</h3>
 <p>If you have enabled metrics support in OpenShift (e.g. with <code>oc cluster up --metrics</code>)
 then you can also install Grafana for Hawkular to visualize your data:</p>
 <pre><code>oc new-app -f https://raw.githubusercontent.com/hawkular/hawkular-grafana-datasource/master/docker/openshift/openshift-template-ephemeral.yaml
 </code></pre><h3 id="external-access">External access</h3>
 <p>In order to enable devices to access Kapua we need to allow external access to the broker&apos;s MQTT connector. In the default deployment there are two ways to achieve this.</p>
 <p>First, the broker exposes MQTT over WebSocket transport. As WebSocket is based on HTTP we can define a router inside the Openshift to get those device connections to the broker.
 For example, if your Openshift deployment is running at the address <code>192.168.64.2</code>, you can connect the <a href="../user-manual/simulator.md">Kura Simulator</a> like this</p>
 <pre><code>java -jar target/kapua-simulator-kura-*-SNAPSHOT-app.jar --broker ws://kapua-broker:kapua-password@broker-eclipse-kapua.192.168.64.2.nip.io:80
 </code></pre><p>Not all MQTT clients have WebSocket support, so we need to enable direct MQTT over TCP access to the broker as well. By default, Kapua comes with the NodePort service that routes all traffic from port <code>31883</code> to the broker.
 So you can connect your MQTT clients directly to this service. For the simulator example similar to the above, that would look something like</p>
 <pre><code>java -jar target/kapua-simulator-kura-1.3.0-SNAPSHOT-app.jar --broker tcp://kapua-broker:kapua-password@192.168.64.2:31883
 </code></pre><p>This is suitable only for the local deployments. In the cloud or production environments, you should deploy a proper LoadBalancer Openshift service to enable external traffic flow to the broker.</p>
 <h3 id="ensuring-enough-entropy">Ensuring enough entropy</h3>
 <p> It may happen that firing up docker containers and starting up application which use
  Java&apos;s <code>SecureRandom</code> (which happens in the next step a few times) run dry the Linux
  Kernel&apos;s entropy pool. The result is that some application will block during startup
  (even longer than 30 seconds) which will trigger OpenShift to kill the pods since they
  are considered unresponsive (which they actually are).</p>
 <p> You can check the amount of entropy the kernel has available with the following command:</p>
 <pre><code> cat /proc/sys/kernel/random/entropy_avail
 </code></pre><p> If this number drops to zero, then the kernel has run out of entropy and application will
  block.</p>
 <p> One solution (there are a few others) is to install <code>haveged</code> a user-space daemon
  which provides entropy to the kernel.</p>
 <p> On CentOS 7 it can be installed with the following commands (all as <code>root</code>):</p>
 <pre><code> yum install epel-release # only if you
  yum install haveged
  systemctl enable --now haveged
 </code></pre><p> As the package comes from the <a href="https://fedoraproject.org/wiki/EPEL" title="Information about EPEL" target="_blank">EPEL repositories</a>.
  If you haven&apos;t yet enabled those repositories, then you need to do this before trying to
  install <code>haveged</code>:</p>
 <pre><code> yum install epel-release
 </code></pre><p> For more information about <code>haveged</code> see <a href="http://www.issihosts.com/haveged/" target="_blank">http://www.issihosts.com/haveged/</a></p>
 <p> For more information about the &quot;EPEL repositories&quot; see <a href="https://fedoraproject.org/wiki/EPEL" target="_blank">https://fedoraproject.org/wiki/EPEL</a></p>
 <h2 id="vagrant">Vagrant</h2>
 <p>Kapua can also be run with Vagrant.</p>
 <h3 id="installing-vagrant">Installing Vagrant</h3>
 <p>Before Vargant can be used to run Kapua it needs to be installed. This is different in each distribution.</p>
 <h4 id="installing-vagrant-on-fedora-25">Installing Vagrant on Fedora 25</h4>
 <p><div class="alert alert-info hints-alert"><div class="hints-icon"><i class="fa fa-info-circle"></i></div><div class="hints-container"><p>Do not use Vagrant from Fedora 25. Kapua requires to use the VirtualBox provide from Vargant and cannot run
 with the <code>libvirt</code> provider which Fedora uses. So it is necessary to install Virtualbox and Vagrant from different locations.</p>
 </div></div> </p>
 <p>Run the following commands in order to install Vagrant (all as <code>root</code>):</p>
 <pre><code>dnf install kernel-devel

 wget https://www.virtualbox.org/download/oracle_vbox.asc
 rpm --import oracle_vbox.asc

 dnf install http://download.virtualbox.org/virtualbox/5.1.14/VirtualBox-5.1-5.1.14_112924_fedora25-1.x86_64.rpm
 dnf install https://releases.hashicorp.com/vagrant/1.9.2/vagrant_1.9.2_x86_64.rpm
 </code></pre><p><div class="alert alert-success hints-alert"><div class="hints-icon"><i class="fa fa-mortar-board"></i></div><div class="hints-container"><p>There may by more up to date versions of the binaries. You should check and install more recent versions, if possible.</p>
 </div></div></p>
 <p><div class="alert alert-danger hints-alert"><div class="hints-icon"><i class="fa fa-exclamation-circle"></i></div><div class="hints-container"><p>By manually installing RPMs you won&apos;t receive updates for those packages. You will need to manually check for security updates and bug fixes.</p>
 </div></div></p>
 <h3 id="running-kapua">Running Kapua</h3>
 <p>After Vagrant is installed you can run Kapua by running:</p>
 <pre><code>cd dev-tools/vagrant
 sudo ./start.sh base-box
 </code></pre>

                                 </section>

     </div>
     <div class="search-results">
         <div class="has-results">

             <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
             <ul class="search-results-list"></ul>

         </div>
         <div class="no-results">

             <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>

         </div>
     </div>
 </div>

                         </div>
                     </div>

             </div>


                 <a href="building.html#documentation" class="navigation navigation-prev " aria-label="Previous page: Documentation">
                     <i class="fa fa-angle-left"></i>
                 </a>


                 <a href="running.html#docker-containers" class="navigation navigation-next " aria-label="Next page: Docker">
                     <i class="fa fa-angle-right"></i>
                 </a>


     </div>

     <script>
         var gitbook = gitbook || [];
         gitbook.push(function() {
             gitbook.page.hasChanged({"page":{"title":"Running","level":"1.3","depth":1,"next":{"title":"Docker","level":"1.3.1","depth":2,"anchor":"#docker-containers","path":"running.md","ref":"running.md#docker-containers","articles":[]},"previous":{"title":"Documentation","level":"1.2.2","depth":2,"anchor":"#documentation","path":"building.md","ref":"building.md#documentation","articles":[]},"dir":"ltr"},"config":{"plugins":["hints"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"hints":{"danger":"fa fa-exclamation-circle","info":"fa fa-info-circle","tip":"fa fa-mortar-board","working":"fa fa-wrench"},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"eclipse/kapua","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Eclipse Kapua™ Developer Guide","links":{"home":"http://eclipse.org/kapua"},"gitbook":"3.x.x","description":"Eclipse Kapua™ Developer Guide"},"file":{"path":"running.md","mtime":"2020-11-02T11:38:11.389Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2020-11-02T11:38:53.020Z"},"basePath":".","book":{"language":""}});
         });
     </script>
 </div>


     <script src="gitbook/gitbook.js"></script>
     <script src="gitbook/theme.js"></script>


         <script src="gitbook/gitbook-plugin-search/search-engine.js"></script>


         <script src="gitbook/gitbook-plugin-search/search.js"></script>


         <script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>


         <script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>


         <script src="gitbook/gitbook-plugin-sharing/buttons.js"></script>


         <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>


     </body>
 </html>

	<!DOCTYPE HTML>
	<html lang="" >
	<head>
	<meta charset="UTF-8">
	<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
	<title>Running · Eclipse Kapua™ Developer Guide</title>
	<meta http-equiv="X-UA-Compatible" content="IE=edge" />
	<meta name="description" content="">
	<meta name="generator" content="GitBook 3.2.2">




	<link rel="stylesheet" href="gitbook/style.css">




	<link rel="stylesheet" href="gitbook/gitbook-plugin-hints/plugin-hints.css">



	<link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">



	<link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">



	<link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">























	<meta name="HandheldFriendly" content="true"/>
	<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
	<meta name="apple-mobile-web-app-capable" content="yes">
	<meta name="apple-mobile-web-app-status-bar-style" content="black">
	<link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
	<link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">


	<link rel="next" href="running.html" />


	<link rel="prev" href="building.html" />


	</head>
	<body>

	<div class="book">
	<div class="book-summary">


	<div id="book-search-input" role="search">
	<input type="text" placeholder="Type to search" />
	</div>


	<nav role="navigation">



	<ul class="summary">









	<li class="chapter " data-level="1.1" data-path="./">

	<a href="./">


	Introduction

	</a>



	</li>

	<li class="chapter " data-level="1.2" data-path="building.html">

	<a href="building.html">


	Building

	</a>



	<ul class="articles">


	<li class="chapter " data-level="1.2.1" data-path="building.html">

	<a href="building.html#kapua">


	Kapua

	</a>



	</li>

	<li class="chapter " data-level="1.2.2" data-path="building.html">

	<a href="building.html#documentation">


	Documentation

	</a>



	</li>


	</ul>

	</li>

	<li class="chapter active" data-level="1.3" data-path="running.html">

	<a href="running.html">


	Running

	</a>



	<ul class="articles">


	<li class="chapter " data-level="1.3.1" data-path="running.html">

	<a href="running.html#docker-containers">


	Docker

	</a>



	</li>

	<li class="chapter " data-level="1.3.2" data-path="running.html">

	<a href="running.html#openshift">


	OpenShift

	</a>



	</li>

	<li class="chapter " data-level="1.3.3" data-path="running.html">

	<a href="running.html#vagrant">


	Vagrant

	</a>



	</li>


	</ul>

	</li>

	<li class="chapter " data-level="1.4" data-path="ide.html">

	<a href="ide.html">


	Setting up an IDE

	</a>



	<ul class="articles">


	<li class="chapter " data-level="1.4.1" data-path="ide.html">

	<a href="ide.html#eclipse">


	Eclipse IDE

	</a>



	</li>


	</ul>

	</li>

	<li class="chapter " data-level="1.5" >

	<span>


	Configuration

	</span>



	<ul class="articles">


	<li class="chapter " data-level="1.5.1" data-path="sso.html">

	<a href="sso.html">


	Single sign-on

	</a>



	</li>


	</ul>

	</li>

	<li class="chapter " data-level="1.6" data-path="database.html">

	<a href="database.html">


	Working with database

	</a>



	</li>

	<li class="chapter " data-level="1.7" data-path="client.html">

	<a href="client.html">


	Client generation

	</a>



	</li>

	<li class="chapter " data-level="1.8" data-path="qa.html">

	<a href="qa.html">


	QA process

	</a>



	</li>




	<li class="divider"></li>

	<li>
	<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
	Published with GitBook
	</a>
	</li>
	</ul>


	</nav>


	</div>

	<div class="book-body">

	<div class="body-inner">



	<div class="book-header" role="navigation">


	<!-- Title -->
	<h1>
	<i class="fa fa-circle-o-notch fa-spin"></i>
	<a href="." >Running</a>
	</h1>
	</div>




	<div class="page-wrapper" tabindex="-1" role="main">
	<div class="page-inner">

	<div id="book-search-results">
	<div class="search-noresults">

	<section class="normal markdown-section">

	<h1 id="running">Running</h1>
	<p>Kapua can be run in a few different ways. See the following chapters for
	more information about how to start and run Kapua.</p>
	<p><div class="alert alert-info hints-alert"><div class="hints-icon"><i class="fa fa-info-circle"></i></div><div class="hints-container"><p>Most of the following descriptions focus on a developer centric
	setup and not on a full blown production setup.</p>
	</div></div></p>
	<h2 id="docker-containers">Docker containers</h2>
	<p>Before running Kapua on Docker, you need to </p>
	<ol>
	<li>Install <code>docker</code> and <code>docker-compose</code></li>
	<li>Run <code>mvn -f assembly -Pdocker</code> once to build containers. Run <code>mvn -f assembly -Pconsole,docker</code> if you also need to build the Web Console image.</li>
	</ol>
	<p>Now, you can start Kapua by using Docker Compose. To do so, run</p>
	<pre><code>kapua/deployment/docker/docker-deploy.sh
	</code></pre><p>After Kapua has been started, you can navigate your browser to <a href="http://localhost:8080" target="_blank">http://localhost:8080</a> and log in using the following credentials:
	<code>kapua-sys</code> : <code>kapua-password</code></p>
	<p>You can access the API using: <a href="http://localhost:8081" target="_blank">http://localhost:8081</a></p>
	<p><strong>Note</strong>: If you are using Docker on Windows the hostname will most likely not be <code>localhost</code> but
	the IP address of your docker instance.</p>
	<p>By default, the <code>latest</code> version of images will be used. If you want to run some other version of Kapua, set the <code>IMAGE_VERSION</code> environment variable, like</p>
	<pre><code>export IMAGE_VERSION=0.2.0
	</code></pre><p>To stop Kapua, run</p>
	<pre><code>kapua/deployment/docker/docker-undeploy.sh
	</code></pre><h2 id="openshift">OpenShift</h2>
	<p>OpenShift is a PaaS (Platform As A Service) platform based on Kubernetes. Kapua supports deployments into <a href="https://www.openshift.org" target="_blank">OpenShift Origin</a>,
	which is an open source community project. Origin sources, can be found <a href="https://www.openshift.org/" target="_blank">here</a>. We support Kapua on OpenShift Origin <strong>1.4.1</strong>.</p>
	<p>Currently we support running OpenShift only on Linux OS. If you would like to run Kapua on Mac OS or on Windows for development purposes, please install Linux
	(for example Fedora 25) into a virtual machine (for example VirtualBox) and install OpenShift there.</p>
	<h3 id="starting-openshift-cluster">Starting OpenShift cluster</h3>
	<p>For running Kapua on an OpenShift you need to
	have OpenShift cluster installed and started in the first place. You can install it by yourself or rely on the script we provides:</p>
	<pre><code>sudo kapua/deployment/openshift/openshift-start.sh
	</code></pre><p>If you are running your OpenShift cluster for the first time, execute the following initialized script as well:</p>
	<pre><code>kapua/deployment/openshift/openshift-initialize.sh
	</code></pre><p>Initialization script is responsible for logging you into a cluster and creating new OpenShift project for Kapua.</p>
	<p>If your Openshift cluster is not on the localhost, set the <code>OPENSHIFT_HOST</code> environment variable. For example, something like</p>
	<pre><code>export OPENSHIFT_HOST=192.168.64.2:8443
	</code></pre><p>If for some reasons, you cannot start your cluster, try to execute the startup script with option <code>DOCKERIZED=FALSE</code>:</p>
	<pre><code>sudo DOCKERIZED=FALSE kapua/deployment/openshift/openshift-start.sh
	</code></pre><p>Option <code>DOCKERIZED=FALSE</code> tells startup script to use standard binary installation of OpenShift Origin instead of Docker-based <code>oc cluster up</code> command.</p>
	<h3 id="deploying-kapua-into-openshift-cluster">Deploying Kapua into OpenShift cluster</h3>
	<p>Now when you have OpenShift cluster up, running and initialized, execute the following script:</p>
	<pre><code>cd kapua/deployment/openshift
	./openshift-deploy.sh
	</code></pre><p>Now open the following URL in your web browser - <code>http://localhost:8080</code>. And log-in into Kapua UI using default
	credentials:</p>
	<dl>
	<dt>username</dt><dd>kapua-sys</dd>
	<dt>password</dt><dd>kapua-password</dd>
	</dl>


	<h2 id="using-minishift">Using Minishift</h2>
	<p>Minishift is a tool that helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM. Follow <a href="https://docs.openshift.org/latest/minishift/getting-started/index.html" target="_blank">this guide</a> for installing and having Minishift up and running.</p>
	<p>Steps to run Kapua on Minishift are the following</p>
	<ol>
	<li><p>Start Minishift (make sure you have enough memory and cpu resources for your cluster)</p>
	<pre><code class="lang-bash"> minishift start --memory 8GB --cpus 4
	</code></pre>
	</li>
	<li><p>Export Minishift docker and oc tools</p>
	<pre><code class="lang-bash"> <span class="hljs-built_in">eval</span> $(minishift docker-env)
	<span class="hljs-built_in">eval</span> $(minishift oc-env)
	</code></pre>
	</li>
	<li><p>Export address of the cluster</p>
	<pre><code class="lang-bash"> <span class="hljs-built_in">export</span> OPENSHIFT_HOST=$(minishift ip):8443
	</code></pre>
	</li>
	<li><p>Initialize Kapua project</p>
	<pre><code class="lang-bash"> kapua/deployment/openshift/openshift-initialize.sh
	</code></pre>
	</li>
	<li><p>Deploy Kapua components</p>
	<pre><code class="lang-bash"> <span class="hljs-built_in">cd</span> kapua/deployment/openshift
	./openshift-deploy.sh
	</code></pre>
	</li>
	<li><p>Visit Minishift console</p>
	<pre><code class="lang-bash"> minishift dashboard
	</code></pre>
	</li>
	</ol>
	<h2 id="advanced-openshift-configuration">Advanced OpenShift configuration</h2>
	<h3 id="external-node-port-for-mqtt">External Node port for MQTT</h3>
	<p>The default setup uses port 31883 to export the MQTT over TCP port of the broker. This means that you can connect
	from outside of the OpenShift cluster to Kapua over port 31883 (instead of port 1883) to Kapua.</p>
	<p>However it is only possible for one service to make use of this port. If you are planning to add a second Kapua installation
	and still want to use the external node port, then you will need to choose a different, yet unsed, port.</p>
	<p>Also see: <a href="https://docs.openshift.com/container-platform/latest/dev_guide/getting_traffic_into_cluster.html" target="_blank">https://docs.openshift.com/container-platform/latest/dev_guide/getting_traffic_into_cluster.html</a></p>
	<h3 id="adding-metrics">Adding metrics</h3>
	<p>If you have enabled metrics support in OpenShift (e.g. with <code>oc cluster up --metrics</code>)
	then you can also install Grafana for Hawkular to visualize your data:</p>
	<pre><code>oc new-app -f https://raw.githubusercontent.com/hawkular/hawkular-grafana-datasource/master/docker/openshift/openshift-template-ephemeral.yaml
	</code></pre><h3 id="external-access">External access</h3>
	<p>In order to enable devices to access Kapua we need to allow external access to the broker's MQTT connector. In the default deployment there are two ways to achieve this.</p>
	<p>First, the broker exposes MQTT over WebSocket transport. As WebSocket is based on HTTP we can define a router inside the Openshift to get those device connections to the broker.
	For example, if your Openshift deployment is running at the address <code>192.168.64.2</code>, you can connect the <a href="../user-manual/simulator.md">Kura Simulator</a> like this</p>
	<pre><code>java -jar target/kapua-simulator-kura-*-SNAPSHOT-app.jar --broker ws://kapua-broker:kapua-password@broker-eclipse-kapua.192.168.64.2.nip.io:80
	</code></pre><p>Not all MQTT clients have WebSocket support, so we need to enable direct MQTT over TCP access to the broker as well. By default, Kapua comes with the NodePort service that routes all traffic from port <code>31883</code> to the broker.
	So you can connect your MQTT clients directly to this service. For the simulator example similar to the above, that would look something like</p>
	<pre><code>java -jar target/kapua-simulator-kura-1.3.0-SNAPSHOT-app.jar --broker tcp://kapua-broker:kapua-password@192.168.64.2:31883
	</code></pre><p>This is suitable only for the local deployments. In the cloud or production environments, you should deploy a proper LoadBalancer Openshift service to enable external traffic flow to the broker.</p>
	<h3 id="ensuring-enough-entropy">Ensuring enough entropy</h3>
	<p> It may happen that firing up docker containers and starting up application which use
	Java's <code>SecureRandom</code> (which happens in the next step a few times) run dry the Linux
	Kernel's entropy pool. The result is that some application will block during startup
	(even longer than 30 seconds) which will trigger OpenShift to kill the pods since they
	are considered unresponsive (which they actually are).</p>
	<p> You can check the amount of entropy the kernel has available with the following command:</p>
	<pre><code> cat /proc/sys/kernel/random/entropy_avail
	</code></pre><p> If this number drops to zero, then the kernel has run out of entropy and application will
	block.</p>
	<p> One solution (there are a few others) is to install <code>haveged</code> a user-space daemon
	which provides entropy to the kernel.</p>
	<p> On CentOS 7 it can be installed with the following commands (all as <code>root</code>):</p>
	<pre><code> yum install epel-release # only if you
	yum install haveged
	systemctl enable --now haveged
	</code></pre><p> As the package comes from the <a href="https://fedoraproject.org/wiki/EPEL" title="Information about EPEL" target="_blank">EPEL repositories</a>.
	If you haven't yet enabled those repositories, then you need to do this before trying to
	install <code>haveged</code>:</p>
	<pre><code> yum install epel-release
	</code></pre><p> For more information about <code>haveged</code> see <a href="http://www.issihosts.com/haveged/" target="_blank">http://www.issihosts.com/haveged/</a></p>
	<p> For more information about the "EPEL repositories" see <a href="https://fedoraproject.org/wiki/EPEL" target="_blank">https://fedoraproject.org/wiki/EPEL</a></p>
	<h2 id="vagrant">Vagrant</h2>
	<p>Kapua can also be run with Vagrant.</p>
	<h3 id="installing-vagrant">Installing Vagrant</h3>
	<p>Before Vargant can be used to run Kapua it needs to be installed. This is different in each distribution.</p>
	<h4 id="installing-vagrant-on-fedora-25">Installing Vagrant on Fedora 25</h4>
	<p><div class="alert alert-info hints-alert"><div class="hints-icon"><i class="fa fa-info-circle"></i></div><div class="hints-container"><p>Do not use Vagrant from Fedora 25. Kapua requires to use the VirtualBox provide from Vargant and cannot run
	with the <code>libvirt</code> provider which Fedora uses. So it is necessary to install Virtualbox and Vagrant from different locations.</p>
	</div></div> </p>
	<p>Run the following commands in order to install Vagrant (all as <code>root</code>):</p>
	<pre><code>dnf install kernel-devel

	wget https://www.virtualbox.org/download/oracle_vbox.asc
	rpm --import oracle_vbox.asc

	dnf install http://download.virtualbox.org/virtualbox/5.1.14/VirtualBox-5.1-5.1.14_112924_fedora25-1.x86_64.rpm
	dnf install https://releases.hashicorp.com/vagrant/1.9.2/vagrant_1.9.2_x86_64.rpm
	</code></pre><p><div class="alert alert-success hints-alert"><div class="hints-icon"><i class="fa fa-mortar-board"></i></div><div class="hints-container"><p>There may by more up to date versions of the binaries. You should check and install more recent versions, if possible.</p>
	</div></div></p>
	<p><div class="alert alert-danger hints-alert"><div class="hints-icon"><i class="fa fa-exclamation-circle"></i></div><div class="hints-container"><p>By manually installing RPMs you won't receive updates for those packages. You will need to manually check for security updates and bug fixes.</p>
	</div></div></p>
	<h3 id="running-kapua">Running Kapua</h3>
	<p>After Vagrant is installed you can run Kapua by running:</p>
	<pre><code>cd dev-tools/vagrant
	sudo ./start.sh base-box
	</code></pre>

	</section>

	</div>
	<div class="search-results">
	<div class="has-results">

	<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
	<ul class="search-results-list"></ul>

	</div>
	<div class="no-results">

	<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>

	</div>
	</div>
	</div>

	</div>
	</div>

	</div>



	<a href="building.html#documentation" class="navigation navigation-prev " aria-label="Previous page: Documentation">
	<i class="fa fa-angle-left"></i>
	</a>


	<a href="running.html#docker-containers" class="navigation navigation-next " aria-label="Next page: Docker">
	<i class="fa fa-angle-right"></i>
	</a>



	</div>

	<script>
	var gitbook = gitbook \|\| [];
	gitbook.push(function() {
	gitbook.page.hasChanged({"page":{"title":"Running","level":"1.3","depth":1,"next":{"title":"Docker","level":"1.3.1","depth":2,"anchor":"#docker-containers","path":"running.md","ref":"running.md#docker-containers","articles":[]},"previous":{"title":"Documentation","level":"1.2.2","depth":2,"anchor":"#documentation","path":"building.md","ref":"building.md#documentation","articles":[]},"dir":"ltr"},"config":{"plugins":["hints"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"hints":{"danger":"fa fa-exclamation-circle","info":"fa fa-info-circle","tip":"fa fa-mortar-board","working":"fa fa-wrench"},"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"eclipse/kapua","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"Eclipse Kapua™ Developer Guide","links":{"home":"http://eclipse.org/kapua"},"gitbook":"3.x.x","description":"Eclipse Kapua™ Developer Guide"},"file":{"path":"running.md","mtime":"2020-11-02T11:38:11.389Z","type":"markdown"},"gitbook":{"version":"3.2.2","time":"2020-11-02T11:38:53.020Z"},"basePath":".","book":{"language":""}});
	});
	</script>
	</div>


	<script src="gitbook/gitbook.js"></script>
	<script src="gitbook/theme.js"></script>


	<script src="gitbook/gitbook-plugin-search/search-engine.js"></script>



	<script src="gitbook/gitbook-plugin-search/search.js"></script>



	<script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>



	<script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>



	<script src="gitbook/gitbook-plugin-sharing/buttons.js"></script>



	<script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>



	</body>
	</html>