Installation of the Hammerserver
This document describes the installation and deployment of the HammerServer. The following topics are covered:
How to install the necessary software.
Action necesssary to initialize the HammerServer's database back end and to configure the server.
Starting, stopping, administration and monitoring.
The installation of all required software consists of no more than unpacking the distribution in a self-chosen directry, e.g. /opt/hammerserver. All necessary files are created under this 'home' directory. Notably the following subdirectories are created:
Directory with all binaries, such as the stop/start script. For ease of use, you can extend the PATH environment to include this directory.
Miscellaneous other files, such as: configuration, database definition scripts.
The documentation for the HammerServer, including this document.
Directory where activity is logged.
Perl modules which are used by the server and by hsclient, the command-line client script.
Offloaded data (database cleaning results) are created here.
The directory bin furthermore contains the script hsenv. After unpacking the software, bin/hsenv may be called to verify that all external Perl modules are present. When hsenv reports missing modules, then these must be added to the Perl installation using cpan.
The storage back end of the HammerServer must currently be a either:
a flat file,
a PostgreSQL database back end,
a CouchDB back end.
If you choose to use the HammerServer with a flat-file back end, which is perfectly good for (a) testing, (b) really fast insertion and retrieval, but slow searching and bulk-validations, or (c) having your data on a write/only medium such as a DVR/R, then the initialization is minimal. Simply configure the HammerServer as described below, then run bin/hs-init-backend go and you're set. The invocation of bin/hs-init-backend sends an initial record to the back end (a ``seed'', or ``chain start'').
If you choose to use the HammerServer with a CouchDB back end, then there is also no need for other initializations than configuring the HammerServer and running bin/hs-init-backend go. This provides initial data (``seeding'').
However, if you choose to use the PostgreSQL back end, then you must define the database and its structure. The database definition is contained in the file etc/db-00.sql. Running this script creates the database hs and assigns it to a user hs, using a password which is stated in the configuration file. The necessary steps are:
Edit etc/db-00.sql and supply self-chosen values for the database user and password;
Run the script, using a command like psql -U postgres < db-00.sql
The database table and one sequence are defined in the file etc/db-01.sql. In most situations the definition will be correct. Advanced DBA's might want to add segment definitions or the like. The following necessary steps are:
Edit etc/db-01.sql for review and optional tweaking;
Run the script using psql -U hs < etc/db-01.sql (this assumes that the database user, defined in the previous step, is called hs).
After this, run bin/hs-init-backend go to provide initial database contents, and you're set to go.
The file etc/hammerserver.cfg configures the HammerServer. You should edit this file, and follow the instructions to set the 'right' values. Notably, the default settings that you might want to edit, are:
The server is configured to listen to the URL http://localhost:10000 and to allow all services (normal, bulk upload, searching, and management).
The type of storage back end (flat file vs. database) may need altering.
You need to modify the default AES key that is used for encryption.
More information on the configuration is contained in the documentation about the control script hsctl.
The script bin/hsctl is used to stop or start (or restart) the HammerServer. For testing, the following actions should be taken:
File log/hammerserverd.log should be monitored using tail -f.
The server is started using bin/hsctl start. Any errors show up either on screen, or in the log.
A test message is inserted using
bin/hsclient http://localhost:10000 insert 'Test message'
Here the URL http://localhost:10000 denotes where the server runs (see the configuration in etc/hammerserver.cfg). The success should be monitored by watching the log file.
For automatic startup, the script can be called from your local start up file /etc/rc.local, or it can be added to the services chain using chkonfig. This depends on the Unix flavor.
The HammerServer writes the log log/hammerserverd.log. In order to avoid disk space exhaustion, this log should be 'rotated' at regular intervals. A good tool to do this, is logrotate. The log file rotation must be configured separately, the HammerServer takes no actions in this respect.
The server does not need to be restarted when the log file is rotated. Log rotation can occur while the server is running.
The server command to offload database contents onto a flat file, creates files in the subdirectory offload. When the database is cleaned, then such files should be moved to a back up medium (so that disk space isn't exhausted).
The tamper-resistant server, all tooling, and the documentation were written by Karel Kubat / karel@e-tunity.com. Copyright (c) 2009 ff. Distributed under GPLV3.