Server Installation and Configuration

The MetaKarta Application Server is installed as follows:

o  On Linux operating systems, use tar -xjvf to extract the software package (.tbz2 format) into the directory of your choice, by default located at:
export MM_HOME=/MetaKarta
Depending on your software installation directory, you may need "root" privileges.

o  On Windows operating systems, use unzip to extract the software package (.zip format) in the directory of your choice, by default located at:
set MM_HOME=C:\MetaKarta
Depending on your software installation directory, you may need "Administrator" privileges. You should avoid using the "Program Files" directories of Windows as they have are now controlled by Windows with special access rights.

Finally, note that this deployment guide assumes the Linux notation for scripts and file location such as $MM_HOME/Setup.sh.
The Windows scripts and file location are matching and therefore can be inferred, in the above example: %MM_HOME%\Setup.bat.

If you are using an existing database and do not wish to customize the application server (e.g. memory allocation, Windows services), then you can skip this step and go directly to the section on Application Server Execution and Initialization

Otherwise, go to the software home directory and execute the $MM_HOME/Setup.sh utility.
Note On Windows, you must "Run as administrator" the %MM_HOME%\Setup.bat utility.
The following options are available:

$MM_HOME/Setup.sh -?

[{ -? | --? | /? | --help }]                     Asking for help

[{ -tp | --tomcat-port }] <int>                  Tomcat: set the port number

[{ -tm | --tomcat-memory }] <int>                Tomcat: set the maximum memory in Mb

[{ -ta | --tomcat-agent }] <true|false>          Tomcat: switch to metadata harvesting only

[{ -ts | --tomcat-service }] <true|false>        Tomcat: install or remove tomcat as a service

[{ -s | --ssl }] <true|false>                    SSL: enable or disable ssl

[{ -sc | --ssl-cert-file }] <file>               SSL: the X.509 file containing the SSL certificate

[{ -sk | --ssl-key-file }] <file>                SSL: the X.509 file containing the SSL key

[{ -sp | --ssl-key-password }] <string>          SSL: the password for the SSL key file

[{ -sr | --ssl-root-chain-file }] <file>         SSL: the X.509 file containing the SSL certificate chain

[{ -ds | --database-service }] <true|false>      Database: install or remove database as a service

[{ -dp | --database-port }] <int>                Database: set the port number

[{ -dc | --database-connection }] <string>       Database: set the connection string

[{ -du | --database-user }] <string>             Database: set the connection user

[{ -dw | --database-password }] <string>         Database: set the connection password

[{ -da | --database-auto-upgrade }] <true|false> Database: automatically run the upgrades on startup

[{ -mh | --mail-host }] <string>                 Email: set the mail server host name

[{ -mp | --mail-port }] <int>                    Email: set the mail server port number

[{ -mu | --mail-user }] <string>                 Email: set the mail user name

[{ -mw | --mail-password }] <string>             Email: set the mail user password

[{ -ms | --mail-sender }] <string>               Email: set the mail sender's address

[{ -mx | --mail-external-url }] <string>         Email: set the external URL to use in email templates

[{ -ma | --mail-admin }] <string>                Email: a comma separated list of emails that will be notified of startup failures

[{ -iu | --index-url }] <string>                 Solr: set the url of the solr server (or internal to use the internal solr server)

[{ -ic | --index-collection }] <string>          Solr: set the name of the collection to use

[{ -ep | --erwin-product }] <string>             Erwin: the edition to switch to: EWP or EDG

[{ -op | --oracle-product }] <string>            Oracle: the edition to switch to: OEMM or OMM4OBI

[{ -ch | --certificate-host }] <string>          Certificate: the host name to retrieve the certificate for

[{ -cp | --certificate-port }] <int>             Certificate: the port number to connect to

[{ -we | --webapp-enable }]... <string>          WebApp: enable the specified webapp (MMDoc)

[{ -wd | --webapp-disable }]... <string>         WebApp: disable the specified webapp (MMDoc)

[{ -wa | --webapp-all }]... <string>             WebApp: allow all ip access to the specified webapp (MIMBWebServices,MMDoc)

[{ -wl | --webapp-local }]... <string>           WebApp: allow only local ip access to the specified webapp (MIMBWebServices,MMDoc)

Alternatively, this Setup utility also offers to setup the configuration parameters defined below through a user friendly application. After any change on any panel (tab) below, remember to press the Configure button in order to perform the configuration changes. A dialog box will be issued to confirm success or failure (with error messages).

o  Database Server tab:
This is to be used only if you wish to use the bundled PostgreSQL database.

-       Enable Windows Service
This will create the 'MM Database Server' Windows Service, set it for automatic start, and actually start it. Note that if no database already exists in $MM_HOME/postgresql/data, then a new database will be created.
Unchecking that box will delete the 'MM Database Server' Windows Service, which is a good idea before uninstalling the MetaKarta software. Note that your existing database in $MM_HOME/postgresql/data will not be deleted as side effect.

-       Port Number
This is set to 5432 which is the default of PostgreSQL but can be changed to avoid conflicts with other servers.

o  Application Server tab:

-       Enable Windows Service
This will create the " MetaKarta Application Server" Windows Service, set it for automatic start, and actually start it. Unchecking that box will delete the " MetaKarta Application Server" Windows Service, which is a good idea before uninstalling the MetaKarta software.

-       Metadata Harvesting Server Only
This allows to setup this application server as a metadata harvesting server only, rather than a full metadata management server. This is very useful in architecture deployments where the metadata management server is:

·  deployed remotely on the cloud but needs to access metadata harvesting servers (agents) locally on premise, or

·  deployed on Linux but needs to access metadata harvesting servers (agents) on a Windows machine where DM/DI/BI client tools are Windows only (e.g. COM based SDK).

-       Metadata Harvesting Browse Path
This controls the access to the file system for metadata harvesting. The default value is set to '*' which means any Windows drive (C: and any mounted remote drive R:) or any directory from root on Linux. It is strongly recommended to limit access to a common shared data location, and avoid system area.

-       Data Directory
This is the location of all data files, including log files as well as the metadata harvesting caching. The data directory is located by default in the 'data' subdirectory of the application server home directory. It is recommended to separate the program data from the program files, this allows you to provide a new location for the data in a separate area (with regular backups if possible). Note that changing to a new location will not move the existing data from the previous location. Either the new location already had the data (from a previous install), or new data will be created.

-       Max Memory
This defines the maximum memory used by Java (JRE) on the MetaKarta Application Server (Apache Tomcat). This is unrelated to the maximum memory used by java on bridges for Metadata Harvesting which is separately set by default with the variable M_JAVA_OPTIONS in $MM_HOME/conf/conf.properties, and can be overridden within the Miscellaneous parameter of memory intensive import bridges (e.g. JDBC).

-       Port Number
This sets a custom start port number by default to avoid conflicts with other web application servers. Note that the MetaKarta Application Server uses 2 consecutive ports. However, this can be set back to 80 to avoid having to specify any port number in the URL.

-       SSL
This enables Secure Socket Layer (SSL) communication for web access (HTTPS). In order to support HTTPS, the MetaKarta Tomcat service must be configured to work with HTTPS for encryption of passwords and other content exchanged between the web client and the MetaKarta Application Server. In this case, you will need a certificate for the HTTPS protocol to work. Note: the MetaKarta software does not perform any error handling for validating a certificate associated with the MetaKarta Application Server, and most web browsers will report an error if the certificate is not provided by a valid certificate authority. Thus, your certificate should be a trusted certificate provided to you by a valid Certificate Authority.

·  Certificate file
Mandatory - Can be a .pem (privacy enhanced electronic mail), .pfx (Windows personal information exchange) or a .jks (Java keystore)

·  Root Certificate file
Optional (only required if the above certificate file was generated by an external company as a certificate authority)

·  Key file
Optional (often it is the case that the certificate file also contains the key)

·  SSL Key Password
Optional (required if the key is password protected)