.. _install-tar:

Installation and Configuration using package in tar format
**********************************************************


Installation
============

Distributed tar package includes Java jar files, prototype configuration files, some
auxiliary scrips and documentation.

.. _deployment-1:

when you install using tar archive, the easiest way to is to place everything in
the same directory: unpacked distribuition archive, configuration files, Python
scripts, logs and reports. NetSpyGlass forms certain directory hierarchy to keep
files organized, for example logs are in the directory `logs`, the database
if in directory `db`, reports are in the directory `reports` and so on.

 - Create role user account "nw2", put its home directory on the file system
   where you have enough room. This can be this user's home directory, e.g.::

    /home/nw2/

   You can start with your own user account instead of nw2 if you plan to just
   evaluate the product and experiment with it.
 - Download and unpack package nw2-NN.tar in this directory (where NN is
   the latest version available). You should get the main binary `netspyglass-1.0.jar`,
   a few startup and auxiliary scripts in subdirectory `bin`, prototype configuration
   file `nw2.conf.minimal`, prototype launch configuration
   file `launch.conf.prototype` and directory  `docs/` with documentation files
 - we recommend you begin with the minimal configuration file which you can
   make by copying `nw2.conf.minimal` under the name `nw2.conf`. Default (full)
   configuration file `doc/default_config/netspyglass.conf` has some advanced
   configuration options you may need in the future.
 - Make sure the directory and all files in it belong to the role account `nw2`.

After you unpack the package, make a copy of the file `nw2.conf.minimal` under
the name `nw2.conf` and edit it. See section :ref:`config-file` for more
details. Also make a copy of the file `launch.conf.prototype` under the name
`launch.conf` and edit it to make sure HOME directory, path to the config file
and directories where the server should keep its logs are set up correctly.
Startup scripts use config file `launch.conf` to start the server and monitor.

File `launch.conf` defines shell variables for all important server parameters
and forms server command line. This file is equivalent of `/etc/default/netspyglass`
configuration file that is used with rpm or deb based installation and has
the same parameters.  See :ref:`etc_default_netspyglass`


Running the Server
==================

We provide shell script `bin/netspyglass` that can be used to start
and stop NetSpyGlass process.


Starting and stopping NetSpyGlass
---------------------------------
Once files `launch.conf` and `nw2.conf` are ready, you can start the server
using script `netspyglass.sh` in subdirectory `bin`.

Script `netspyglass.sh` accepts the following commands supplied to it as a single
command line parameter:

 - start     start both components and exit
 - stop      stop both components
 - status    check if NetSpyGlass is running and print report

To start NetSpyGlass this way, use command::

    ./netspyglass.sh start

To stop it, use::

    ./netspyglass.sh stop

Script `netspyglass.sh` expects to find the main configuration file `nw2.conf` in
the current directory.

If for some reason you can't use `netspyglass.sh stop` to stop it, you can kill
the process running Java class Nw2Ui with lower process id (out of two
with the same name and command line).

If you only plan to start and stop the system manually, this is all you need to do.
You can skip following sections.



Upgrade
-------

To upgrade to the new version, do the following:

 - stop the system using command::

    ./netspyglass.sh stop

 - back up current version (the whole directory)
 - unpack new version in the same directory, on top of the old one, then start
   it again::

    ./netspyglass.sh start


Starting the server for the first time
--------------------------------------

Once you start the server, watch log files `logs/info.log` and `logs/error.log`
for errors. Standard output and standard error streams of the server are written to files
`logs/stdout` and `logs/stderr`. Typical errors at this stage are:

 - config file syntax errors
 - port conflicts (port used by the embedded web server is specified by the config parameter `ui.url`)

Once the serer is up and running and you dont get any errors, connect to it with
your browser using url configured in the config file parameter `ui.url`.