.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

..   http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.

Install Apache Wave
===================

Wave in a Box is delivered as a Java application. Installation comprises installing the server code and (optionally)
configuring federation with XMPP.

.. toctree::

   build
   logging
   run-export

Server installation
-------------------

Getting Java
^^^^^^^^^^^^

Ensure you have Java 6 installed before attempting to install Wave in a Box

Building the code
^^^^^^^^^^^^^^^^^
WIAB is currently distributed on in source code form. Obtain the source for the project:

::

   $ svn co https://svn.apache.org/repos/asf/incubator/wave/trunk
   $ cd wave-protocol
   $ ant

If the build is successful you should see:

::

   BUILD SUCCESSFUL
   Total time: NN minutes MM seconds

Running the server
------------------
Copy the run-nofed-config.sh.example to run-config.sh, then edit run-config.sh to configure it to your setup.
The example file explains the configuration options. You can ignore all those concerning federation and certificates
for now.

Run the server with

::

   $ ./run-server.sh

Running the client
------------------

The configuration in run-config.sh is used by the client too, so nothing extra should be necessary to run the console
client.

::

   $ ./run-client-console.sh <username>

Running the webclient
---------------------

Once you have followed the instructions on this page about how to get the server running you should be able to reach the
web client by going to: http://localhost:9898 when running locally or by contacting port 9898 on the machine running the
server. Note that if you have changed the websocket server port in your settings you should use that port instead.

Mongo DB Installation (optional)
--------------------------------

It is possible to use Mongo DB to store Waves, instead of a filesystem-based system.

Download and extract the MongoDB `distribution <http://www.mongodb.org/>`_ for your system.

By default MongoDB will store data in /data/db/ which means you need to create and set the properties for that folder.
You can use any other location if you'd like just remember to give the server the --dbpath option. ::

   sudo mkdir -p /data/db/
   sudo chown `id -u` /data/db/

Run the server in a terminal window or use whatever means necessary to start the server process:
./<mongodb_location>/bin/mongod.

You can test whether it works by running ./<mongodb_location>/bin/mongo.

* Default connection port: 27017
* Default webadmin port: 28017

For more information read the `manual <http://www.mongodb.org/display/DOCS/Manual>`_.

Running the Server as a Windows Service (optional)
--------------------------------------------------

It is possible to run Wave in a Box as a Windows Service, so it starts and stops automatically.
See :ref:`Run-Wave-as-a-Windows-Service`

.. toctree::
   :hidden:

   Wave-As-Service


Federation configuration (optional)
-----------------------------------

The server conforms to XEP-0114, the Jabber Component Protocol. The first step in
running the Federation Prototype Server is to install an XMPP server that is
XEP-0114 compatible.

Follow the instructions below for your server of choice:

* :ref:`Openfire-Installation`
* :ref:`Prosody-Installation`

There are many XEP-0114 compatible XMPP servers and we don't have instructions for
all of them. Please contribute instructions if you have them for a server we don't
have listed.

See :ref:`federation-background` the explanation of DNS, SRV records, and ports.

.. toctree::

   federation

Configure Your XMPP Server
--------------------------

WIAB runs as a separate process that communicates with the XMPP server. For that communication to take place the XMPP
server has to be notified of which port the WIAB extension will be using and also will need a shared secret for security
purposes. In your XMPP server enable external components on port 5275 and a default shared secret of your own choosing.
The extesion should be named wave.<domain-name> where <domain-name> is the domain name of your XMPP server. You will
also need to enable Server Dialback for server to server communication. Each type of XMPP server is configured
differently, so look to their specific installation instructions for details.

Security
--------

The following changes are not required for the wave extension to work, but are good practices if you are running a
public facing XMPP server.

* Disable inband account registration.
* Disable anonymous login
* Enable server-server compression
* Disable file proxy transfer

Wave Extension Installation
---------------------------
To run the extension you will need some of the parameters you used to set up the XMPP server. They are the extension
port, the extension shared secret, the server name, and finally the component name which is "wave".

The wave server requires a set of certificates used for signing deltas. Please see the [certificates|:ref:`Certificates`
page for help generating these.

Copy the *run-config.sh.example* to *run-config.sh*, then edit *run-config.sh* to configure it to your setup.

When you're done editing the script, run check-certificates.sh to verify that the certificates are configured correctly:

::

   $ ./check-certificates.sh

If that runs successfully then run the server:

::

   $ ./run-server.sh