Deploying a METAMOD application

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.

For development/testing we strongly recommend you use virtualenv.pl to generate a bash script ./bin/activate which sets the relevant environment variables. This can then be sourced in the shell so you don't need to supply the config dir parameter to every script.

Note that activate also will add most METAMOD scripts to your path, so you don't have to prefix every command with the path name.

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.

Optional method: Setting the environment manually

If for some reason you cannot use activate (e.g. sudo restrictions), you must instead set the necessary environment variables 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. Unless running in production environments, use bin/activate wherever possible.

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/userinit/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.

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

Now try starting Catalyst by running

  $ ./bin/activate        # if not done already
  $ metamodweb_server.pl

MetamodWeb should now be available on http://localhost:3000/ using any browser running on the same computer. If successful you should see the METAMOD search interface in your browser at the above link. Stop it with ctrl-c when finished testing.

If using a remote server, use one the following methods for testing:

Other METAMOD daemons (FIXME)

These daemons are normally not used during development unless testing specific functionality. You may start them if needed (add path if not included in PATH).

  $ upload_monitor
  $ ftp_monitor
  $ prepare_download
  $ harvester.pl
  $ create_thredds_catalogs.pl

That's all, folks!

Congratulations! You have now a working METAMOD installation!