trunk/releases/0.11/src/site/twiki/Distributed-mode.twiki

---+Distributed Mode


Following are the steps needed to package and deploy Falcon in Embedded Mode. You need to complete Steps 1-3 mentioned
 [[InstallationSteps][here]] before proceeding further.

---++Package Falcon
Ensure that you are in the base directory (where you cloned Falcon). Let’s call it {project dir}

<verbatim>
$mvn clean assembly:assembly -DskipTests -DskipCheck=true -Pdistributed,hadoop-2
</verbatim>


<verbatim>
$ls {project dir}/distro/target/
</verbatim>

It should give an output like below :
<verbatim>
apache-falcon-distributed-${project.version}-server.tar.gz
apache-falcon-distributed-${project.version}-sources.tar.gz
archive-tmp
maven-shared-archive-resources
</verbatim>

   * apache-falcon-distributed-${project.version}-sources.tar.gz contains source files of Falcon repo.

   * apache-falcon-distributed-${project.version}-server.tar.gz package contains project artifacts along with it's
dependencies, configuration files and scripts required to deploy Falcon.


Tar can be found in {project dir}/target/apache-falcon-distributed-${project.version}-server.tar.gz . This is the tar
used for installing Falcon. Lets call it {falcon package}

Tar is structured as follows.

<verbatim>

|- bin
   |- falcon
   |- falcon-start
   |- falcon-stop
   |- falcon-status
   |- falcon-config.sh
   |- service-start.sh
   |- service-stop.sh
   |- service-status.sh
   |- prism-stop
   |- prism-start
   |- prism-status
|- conf
   |- startup.properties
   |- runtime.properties
   |- client.properties
   |- prism.keystore
   |- log4j.xml
   |- falcon-env.sh
|- docs
|- client
   |- lib (client support libs)
|- server
   |- webapp
      |- falcon.war
      |- prism.war
|- oozie
   |- conf
   |- libext
|- hadooplibs
|- README
|- NOTICE.txt
|- LICENSE.txt
|- DISCLAIMER.txt
|- CHANGES.txt
</verbatim>


---++Installing & running Falcon

---+++Installing Falcon

Running Falcon in distributed mode requires bringing up both prism and server.As the name suggests Falcon prism splits
the request it gets to the Falcon servers. It is a good practice to start prism and server with their corresponding
configurations separately. Create separate directory for prism and server. Let's call them {falcon-prism-dir} and
{falcon-server-dir} respectively.

*For prism*
<verbatim>
$mkdir {falcon-prism-dir}
$tar -xzvf {falcon package}
</verbatim>

*For server*
<verbatim>
$mkdir {falcon-server-dir}
$tar -xzvf {falcon package}
</verbatim>


---+++Starting Prism

<verbatim>
cd {falcon-prism-dir}/falcon-distributed-${project.version}
bin/prism-start [-port <port>]
</verbatim>

By default,
* prism server starts at port 16443. To change the port, use -port option

* falcon.enableTLS can be set to true or false explicitly to enable SSL, if not port that end with 443 will
automatically put prism on https://

* prism starts with conf from {falcon-prism-dir}/falcon-distributed-${project.version}/conf. To override this (to use
the same conf with multiple prism upgrades), set environment variable FALCON_CONF to the path of conf dir. You can find
the instructions for configuring Falcon [[Configuration][here]].

*Enabling prism-client*
*If prism is not started using default-port 16443 then edit the following property in
{falcon-prism-dir}/falcon-distributed-${project.version}/conf/client.properties
falcon.url=http://{machine-ip}:{prism-port}/


---+++Starting Falcon Server

<verbatim>
$cd {falcon-server-dir}/falcon-distributed-${project.version}
$bin/falcon-start [-port <port>]
</verbatim>

By default,
* If falcon.enableTLS is set to true explicitly or not set at all, Falcon starts at port 15443 on https:// by default.

* If falcon.enableTLS is set to false explicitly, Falcon starts at port 15000 on http://.

* To change the port, use -port option.

* If falcon.enableTLS is not set explicitly, port that ends with 443 will automatically put Falcon on https://. Any
other port will put Falcon on http://.

* server starts with conf from {falcon-server-dir}/falcon-distributed-${project.version}/conf. To override this (to use
the same conf with multiple server upgrades), set environment variable FALCON_CONF to the path of conf dir. You can find
 the instructions for configuring Falcon [[Configuration][here]].

*Enabling server-client*
*If server is not started using default-port 15443 then edit the following property in
{falcon-server-dir}/falcon-distributed-${project.version}/conf/client.properties. You can find the instructions for
configuring Falcon here.
falcon.url=http://{machine-ip}:{server-port}/

*NOTE* : https is the secure version of HTTP, the protocol over which data is sent between your browser and the website
that you are connected to. By default Falcon runs in https mode. But user can configure it to http.


---+++Using Falcon

<verbatim>
$cd {falcon-prism-dir}/falcon-distributed-${project.version}
$bin/falcon admin -version
Falcon server build version: {Version:"${project.version}-SNAPSHOT-rd7e2be9afa2a5dc96acd1ec9e325f39c6b2f17f7",
Mode:"embedded"}

$bin/falcon help
(for more details about Falcon cli usage)
</verbatim>


---+++Dashboard

Once Falcon / prism is started, you can view the status of Falcon entities using the Web-based dashboard. You can open
your browser at the corresponding port to use the web UI.

Falcon dashboard makes the REST api calls as user "falcon-dashboard". If this user does not exist on your Falcon and
Oozie servers, please create the user.

<verbatim>
## create user.
[root@falconhost ~] useradd -U -m falcon-dashboard -G users

## verify user is created with membership in correct groups.
[root@falconhost ~] groups falcon-dashboard
falcon-dashboard : falcon-dashboard users
[root@falconhost ~]
</verbatim>


---+++Stopping Falcon Server

<verbatim>
$cd {falcon-server-dir}/falcon-distributed-${project.version}
$bin/falcon-stop
</verbatim>

---+++Stopping Falcon Prism

<verbatim>
$cd {falcon-prism-dir}/falcon-distributed-${project.version}
$bin/prism-stop
</verbatim>