Deploying a METAMOD application

Back to Index

Before you can deploy a METAMOD application you must set up a configuration directory, see METAMOD Configuration.

After the initial configuration has been completed, a number of scripts must be run before the application is up and running.

Setting the environment

Before running any other scripts you must tell METAMOD where to find its libraries.

Method A: Using virtualenv.pl

For simplicity you may use virtualenv.pl to generate a bash script ./bin/activate which sets the relevant environment variables. This can then be sourced in all your scripts without the need to supply the config dir parameter.

From anywhere execute the following command:

  $ cd <PATH TO CONFIGURATION DIR>
  $ /opt/metno-metamod-2.13/virtualenv.pl .
  $ source ./bin/activate

This will enable the correct environment. To disable the environment again type:

  $ deactivate

./bin/activate replaces the bash script activate_env, which is now deprecated.

Method B: Setting the environment manually

  $ export PERL5LIB="/opt/metno-metamod-2.13/local/lib/perl5"

If desired you may also predefine the application config path. Then you won't have to specify the <config> parameter for each script.

  $ export METAMOD_MASTER_CONFIG="/path/to/applic/config"

All commands also run without these variables, but you must then specify the correct executable paths, configuration directory and PERL5LIB for every command, which is rather cumbersome.

Creating the webrun directory

The application also needs several directories to store files during operation. Run the script

  $ common/prepare_runtime_env.sh <config>

which will initialize a runtime directory used by the application for logging, temporary files etc. owned by the APPLICATION_USER user. If already existing nothing will be deleted, although file ownership may be updated to the current configuration. (Note that if your current user does not have write privileges to WEBRUN_DIRECTORY this script will fail.)

Initializing the BASE module

At this point, the deployment of the application is complete for all instances not using the BASE module. For an application using the BASE module, a few steps remains:

As explained in the Data base paragraph, several METAMOD applications may co-operate in a cluster, and share a common data base. One of these applications must use the BASE module, and no other. The last steps (described below) required for the base application must be done after the initial steps (described above), for all applications in the cluster, are completed.

Creating databases

The two PostgreSQL databases used by the cluster must be initialized. Note that the two databases are operated through two database users. The name of these users are found in the master_config.txt file as the value of PG_ADMIN_USER and PG_WEB_USER configuration variables. These users must be defined in the PostgreSQL database environment before the database initialization scripts can be run:

  $ base/init/createusers.sh

It is only necessary to run this script once for a PostgreSQL database environment.

The first SQL database initialization script will create the Meta database.

  $ base/init/create_and_load_all.sh

This script will create the database, and load the static content of the database (taken from staticdata/searchdata.xml). You may check the output of this script in the create_and_load_all.out file in the directory where you are running the command.

The next SQL database initialization script will create the User database.

  $ base/init/run_createuserdb.sh

Note that this script must only be used during setup of a completely new METAMOD cluster. If a User database already exists, all data in the database will be lost. If this should happen, you must recreate the database from a backup copy you hopefully have. But METAMOD will not by itself ensure that such a backup exists.

This warning is only adequate for the run_createuserdb.sh script. The other scripts in this paragraph (prepare_runtime_env.sh, create_and_load_all.sh) may all be used on an existing installation, without harming existing data. The create_and_load_all.sh script will take some time to complete, though. On an existing installation, all metadata in the database will be loaded from the XML archive.

Email configuration (FIXME)

To configure exim, run:

  $ sudo dpkg-reconfigure exim4-config

See the Exim documentation for more information.

Installing services

After installation of the software and one or more configurations, you should now install the application services where the operating system can find it. Currently only Debian-based Linux systems are supported.

This script will create an Apache configuration file, as well as init.d scripts for automatic starting and stopping of Catalyst and the various METAMOD services for the specific application. These files are normally owned by root and will be placed in in <configuration dir>/etc, and then symlinked into /etc/apache2 and /etc/init.d.

  $ cd /opt/metno-metamod-2.13 # or elsewhere if installed from source
  $ ./install_jobs.sh <config>

Users with restricted sudo privileges

Some users may not have full sudo rights, and/or having PERL5LIB stripped out when running under sudo (see http://www.sudo.ws/sudo/alerts/perl_env.html). You will then typically get the following error message:

  sudo: sorry, you are not allowed to set the following environment variables: PERL5LIB

If so you may run install_jobs with the -u option (for unprivileged), in which case all files will be owned by yourself instead of root:

  $ ./install_jobs.sh -u <config>

Note that this is not recommended in production environments where several login users are administering the system.

Starting METAMOD

There are two ways of starting METAMOD; either as a system service (recommended for production environments) or as a series of command line script (recommended for development). In the latter case you would normally run the Catalyst web server continously and start the other daemons as necessary (prepare_download, harvester et al).

Catalyst daemon

First, try starting Catalyst by running

  $ export PERL5LIB=/opt/metno-metamod-2.13/common/lib:/opt/metno-metamod-2.13/catalyst/lib:/opt/metno-metamod-2.13/local/lib/perl5
  $ /opt/metno-metamod-2.13/catalyst/script/metamodweb_server.pl -d myapp

replacing the path to METAMOD on line 2 if running from source.

MetamodWeb should now be available on http://localhost:3000/. If all set you should see the METAMOD search interface. Stop with ctrl-c.

If that worked, you may then try to start it as a service:

  $ sudo /etc/init.d/catalyst-APPLICATION_ID start

Apache

Accessing METAMOD directly from Catalyst is not recommended in production; instead a proxy server like Apache is recommended. ./install_jobs.sh automatically generates the necessary Apache setup files for you.

If this has not already been done you need to enable the Apache proxy modules. Look in /etc/apache2/mods-enabled to see if they have already been enabled.

  $ sudo a2enmod proxy
  $ sudo a2enmod proxy_http

Restart Apache:

  $ sudo apache2ctl restart

or if the site is busy:

  $ sudo apache2ctl graceful

which will wait until all connections are terminated before restarting.

The site should now hopefully be available on

  http://localhost/APPLICATION_ID

METAMOD services

Start METAMOD:

  $ sudo /etc/init.d/metamodServices-APPLICATION_ID start

This should start the required services daemons.