How to configure and install

Installing 2.10 (draft)

$ sudo apt-get install metno-perl-webdev-ver1
$ sudo apt-get install metno-metamod-2.10

If the latter package not available (or you need devel version):

$ curl -O http://repo.met.no/devel/dists/lucid/main/binary-all/web/metno-metamod-2.10_2.10.0-2_all.deb
$ sudo dpkg -i metno-metamod-2.10_2.10.0-2_all.deb

Copy the example config:

$ cp -r /opt/metno-metamod-2.10/app/example .

Then edit example/master_config.txt as needed. For testing, set APPLICATION_USER to your own login.

$ /opt/metno-metamod-2.10/common/prepare_runtime_env.sh example
$ export PERL5LIB=/opt/metno-metamod-2.10/common/lib:/opt/metno-metamod-2.10/catalyst/lib:/opt/metno-perl-webdev-ver1/lib/perl5

Try starting Catalyst:

$ /opt/metno-metamod-2.10/catalyst/script/metamodweb_server.pl example

MetamodWeb should now be available on http://localhost:3000/

This documentation below is outdated for versions after 2.6 and needs a serious rewrite.

Dependencies

This software depends on the following external software which is not part of the METAMOD 2.x distribution:

Linux operating system. METAMOD 2.x should work on other UNIX-like operating systems, but this is not tested.

Mail system

PostgreSQL database system. Tested on version 8.1

Apache 2.x web server with PHP 5.x installed, including pgsql, libxml

Perl v5.8 with the following Perl modules: File::Copy, File::Path, XML::Simple, XML::LibXML, XML::LibXSLT, DBI, DBD::Pg, Geo::Proj4, Mail::Mailer, PDL, PDL::NetCDF, LWP::UserAgent

NetCDF software

ImageMagick

curl, php5-curl (for fimex functionality)

Ubuntu 8.04 (Hardy)

The following packages are required:

exim4; dpkg-reconfigure exim4-config

postgresql-8.3

postgresql-contrib-8.3

libapache2-mod-php5

php5-pgsql

libconfig-tiny-perl

libdbd-pg-perl

libxml-simple-perl

libxml-libxslt-perl

libmailtools-perl

libwww-perl

pdl

libnetcdf-dev

netcdf-bin

proj

imagemagick

gcc

make

mailx (test only)

libxml2-utils (test only)

subversion (test only)

libdatetime-perl (test only)

php5-curl (fimex reprojection)

php-auth

php-db

php-log

In addition, the following CPAN packages do not exist in etch and need to be installed separately:

Geo::Proj4

PDL::NetCDF

Note: several people (including me) have seen problems when installing postgresql. The reason is not clear, but a

sudo dpkg -P postgresql-8.3 postgresql-client-8.3
sudo apt-get install postgresql-8.3

seems to help in lots of cases.

Changes for 2.4

New packages:

php5-gd

php5-xsl

postgresql-8.3-postgis

Removed packages:

imagemagick

php5-curl

Debian Etch

The following packages are required on Debian Etch to fulfil the requirements:

exim4

postgresql-8.1

apache2-mpm-prefork

libapache2-mod-php5

php5-pgsql

libdbi-perl

libdbd-pg-perl

libxml-simle-perl

libxml-libxslt-perl

libmailtools-perl

libwww-perl

pdl

netcdf-bin

netcdf-dev

proj

imagemagick

gcc

make

libdatetime-perl (test only)

mailx (test only)

libxml2-utils (test only)

In addition, the following CPAN packages do not exist in etch and need to be installed separately:

Geo::Proj4

XML::XPathContext

PDL::NetCDF

Directory structure

The top METAMOD 2.x directory is divided into one subdirectory for each module (base, search, upload and quest). In addition, one subdirectory (app) contains an example application.

The module directories shares a common structure. During installation of an application, a new directory is created (the target directory), and all module directories are merged into this target directory. In each module directory there is a htdocs subdirectory. The htdocs directories for all the selected modules are in the same way merged into one htdocs subdirectory in the target directory. To avoid name collisions, the actual HTML and PHP files etc. are contained within subdirectories of the htdocs directory. For example, all such files are contained in the directory htdocs/sch for the METAMODSEARCH module, and htdocs/upl for the METAMODUPLOAD module. On the target directory, there will be a htdocs directory containing both the sch and the upl subdirectories. Some htdocs subdirectories may be shared among several modules. For example, the METAMODBASE module and the METAMODQUEST module both have files in the adm subdirectory. Special care must be taken for these files to avoid name collisions.

Each module directory must also contain a file 'filelist.txt' which lists all files comprising the module.

The app directory contains one subdirectory for each application. In each of these application directories there must be a configuration file called 'master_config.txt', and a 'filelist.txt' file containing a list of files that are specific for the application (image files, style sheets etc.). Application directories may also be found outside the METAMOD 2.x source tree.

System Configuration

The following values should be configured in the php.ini file

track_errors = On
upload_max_filesize = 100M
post_max_size = 100M

The following values are an advantage to use in postgresql.conf:

random_page_cost = 2.0

Configuration

The source files within the METAMOD 2.x directories contain a variety of file types (PHP, Perl, XML, HTML/XHTML, CSS and shell-script files, some of them with embedded SQL). The source files are not intended to be used directly, but must be modified and copied to a target directory tree before the application can run. The reason for this is to apply a unified configuration method for all the different file types.

An application directory must contain a file, master_config.txt, which is the master configuration file for the application:

This file contains lines as follows:

VARNAME = VALUE

'VARNAME' must be all uppercase letters [A-Z], underscore or digits. Any number of white space characters may separate 'VARNAME' and '=', and also '=' and 'VALUE'. 'VALUE' starts with the first non-whitespace character and ends with the last non-whitespace character on the line. Additional lines may be appended to 'VALUE' immideately after the initial 'VARNAME = ...' line. Such lines must start with a space character. No whitespace are removed from such appended lines.

VALUEs may be empty, which sometimes indicate that some aspect of the software is turned off. An empty value is indicated by having no characters (or only whitespace characters) after the '=' character.

In addition, comment lines, starting with '#', may be found. Blank lines are ignored.

In the source files, all text strings like:

[==VARNAME==]

will be substituted with the corresponding value when the files are modified and moved to the target directory. Such text strings may also be found within 'VALUE' strings, and they will be substituted as appropriate.

One variable is mandatory in master_config.txt: TARGET_DIRECTORY. This is the directory name of the target directory, the top level of the target directory tree.

The following variables are used to select the modules that will comprise the application. They also identify the absolute path of the source directory for each module:

METAMODBASE_DIRECTORY
METAMODSEARCH_DIRECTORY
METAMODUPLOAD_DIRECTORY
METAMODQUEST_DIRECTORY
METAMODHARVEST_DIRECTORY

If any of these variables are missing, the corresponding modules will not be part of the application.

Each application delivering data to a database (an application with the METAMODUPLOAD and/or the METAMODQUEST module) must have a short acronym that uniquely identify the application for the database. This acronym is included in the master_config.txt file as the value of variable APPLICATION_ID.

Installation

To install an application, the following installation script (located in the top METAMOD 2.x directory) should be run with one argument:

update_target.pl application_directory

The argument is the absolute or relative path of the application directory, the directory containing the master_config.txt file for the application.

For each module selected by the configuration file, there is a filelist.txt list of files in the corresponding module directory. The installation script will copy all the files in these lists to the target directory tree (given by TARGET_DIRECTORY in the configuration file). In the same way, files in the application specific filelist.txt file (located in the application directory) will be copied to the target directory tree. If any file name collision occur between the module file lists and the application file list, the file in the application file list is used. Thus, it is possible to substitute any file in any module with an application specific file, although this mechanism is primarily meant for image files, style sheets etc. Name collisions between files from different modules are supposed not to occur.

While copying the files, the script will perform all substitutions prescribed in the configuration file. The script will only copy files that are modified later than the corresponding target files (or the target file does not exist). Directories will be created as needed.

Some files (e.g. binary files like image files etc.) are not intended for this kind of modification. To avoid substitution on such files, the file names must be prepended with '=' in filelist.txt.

The file pathes in each filelist.txt file must all be relative to the corresponding top module directory (or the application directory). The copied files will keep these relative pathes on the the target directory.

Multiple target files

It is possible to use the configuration file to produce several target files from a single source file. This is done using the special directives:

!substitute_to_file_with_new_name sourcefilepath => targetfilepath
!end_substitute_to_file_with_new_name

The 'sourcefilepath' must be a relative file path found in one of the filelist.txt files, and 'targetfilepath' must also be a relative file path, but it is not required to exist in any filelist.txt file. The source file (given by 'sourcefilepath') will be modified and copied to the target file (given by 'targetfilepath') using the ordinary substitution directives in the configuration file. In addition to these substitutions, any substitution directive between the '!substitute_to_file_with_new_name' directive and the corresponding '!end_substitute_to_file_with_new_name' directive will be performed. Note that these substitution directives will not affect any of the other files produced by the installation script.

By using these special directives several times for the same source file, and varying the target file name between each use, several target files are produced from the same source file, and they will have different content depending on the in-between substitution directives found for each target file.

Initialization

See How to test the software.