Install Miva Merchant Empresa on UNIX

Note: If you are not a system administrator, you will not be able to perform the installation as described below.

Installing the Miva Merchant Empresa enables your server to run (execute) compiled MivaScript applications. These installation instructions provide only the basic information to get the Miva Merchant Empresa up and running quickly. After completing installation, you may refer to the Configure Miva Merchant Empresa VM for UNIX for specific configurations and directives.

About Installation Modes

Miva Merchant Empresa provides two installation modes: Server Safe Mode (the preferred method); and Standard Mode. To determine which installation mode is best for your situation and requirements, review the following descriptions, advantages, and disadvantages for both modes.

Server-Safe Mode Installation: Advantages and Disadvantages

This mode (which requires root level privileges) is typically used when the System Administrator is configuring Miva Merchant Empresa for use by multiple users or virtual hosts on the Web server.

- Advantages of Server-Safe Mode
  - Running a single instance of the executable
  - MivaScript applications can be globally configured for redirection (also called short style URLs)
  - Configurable with 3.x and 4.x configuration libraries
    Note: 4.x has more configuration options available
  - Virtual Host will run faster using the 4.x configuration
- Disadvantages of Server-Safe Mode
  - Requires root level privileges to perform the installation.

Note: The Virtual Hosts will run most efficiently using the 4.x configuration. However, you can configure the Miva Merchant Empresa 4.x VM to use your existing 3.x configuration with miva.conf and the authfile.

Standard Mode Installation: Advantages and Disadvantages

This mode can be used on a Web server to install Miva Merchant Empresa for private use; there must be a private cgi-bin into which the installation can be performed.

Note: If running suexec, use the 3.x standard mode installation.

- Advantages of Standard Mode
  - Installation can be performed by any user with telnet access.
  - It's easy to configure.
- Disadvantages of Standard Mode
  - Does not support ~user style URLs.
  - Does not support multiple data directories.
  - Cannot be configured for redirection (short style URLs) without administrative privileges.
  - Must use 3.x configuration library
  - Virtual Hosts will run slower, since they must be entered in the .conf file.

Install Preparation

Note: Review current Release Notes that contain descriptions of new features and/or program corrections that may require a configuration change.

Place the Miva Merchant Empresa VM 5.x distribution file into a temporary directory and change to that directory.
If your file ends with .gz, gunzip the Miva Merchant Empresa VM 5.x distribution file.
Untar the Miva Merchant Empresa VM 5.x distribution file, for example:

tar -xvf mivavm-vx.xx-platform.tar

Where x.xx is the version of the program.
Refer to Distribution File Contents to view the content and untarred directory tree of the Miva Merchant Empresa VM distribution file,
miva-vx.xx-cgi-platform.tar.gz (some files do not have the .gz).

4x Server Safe Mode Installation

Two configuration libraries are included with Miva Merchant Empresa VM. The following basic installation uses the 4x configuration library, env.so.

Copy and rename mivavm-vx.xx.
- Copy mivavm-vx.xx binary to the system-wide cgi-bin directory mivavm-vx.xx (the Miva Merchant Empresa VM binary) is located in the cgi-bin subdirectory of the distribution.
- Rename mivavm-vx.xx to mivavm.
Change the setuid permissions of mivavm binary. Enter the following commands directly at the server or via telnet:

chown root mivavm
chmod 4755 mivavm

Note: Changing the Miva Merchant Empresa VM binary file's setuid to the root, allows it to downgrade its permissions to the owner of the MivaScript application file.
Copy and rename env.so.
- Copy env.so to system-wide/cgi-bin. env.so is a configuration file, and is located in the lib/config subdirectory of the distribution.
- Rename env.so to libmivaconfig.so The Engine looks first in the current directory for the configuration library, libmivaconfig.so. (Alternatively, the MvCONFIG_LIBRARY environment variable could set the path and filename. See the Miva Merchant Empresa UNIX Configuration Reference Manual.)
Copy the lib/builtins and /certs directories. (See paths, in next step.)

Enter these directives into your httpd.conf (or srm.conf):


SetEnv MvCONFIG_DIR_MIVA /home/miva_user/public_html (path to MivaScript files, usually the same as the DocumentRoot on server)
SetEnv MvCONFIG_DIR_DATA /home/miva_user/mivadata (path to Miva Merchant Data files)
SetEnv MvCONFIG_DIR_BUILTIN /miva_user/local/miva/lib/builtins (path to built-in libraries, these are not Commerce Libraries
SetEnv MvCONFIG_DIR_CA /home/miva_user/public_html/certs (path to SSL certificate files)
SetEnv MvCONFIG_SSL_OPENSSL /home/user/lib/libssl.so (path and file name to the OpenSSL library file, libssl.so)
SetEnv MvCONFIG_SSL_CRYPTO /home/user/lib/libcrypto.so (path and file name to the OpenSSL library file)
SetEnv MvCONFIG_COMMERCE_<method> /home/user/lib/commerce/library.so (method, path, and file name for each installed commerce library)
SetEnv MvCONFIG_DATABASE_<method> /path/to/lib/ (method, path, and file name for mivasql or mysql)

Caution: Data directories must not be accessible via a Web browser. To prevent unauthorized access to the Miva Merchant Empresa VM data files, be sure the data directories are placed outside the web accessible hierarchy. For example, do not put the mivadata directory under the Miva Merchant html directory. Sample Server Configuration:

/www/sitename
/cgi-bin	<- Empresa VM binary and configuration file
/public_html	<- Miva Script root directory
/miva_data	<- Miva data directory

Add the valid extension type to the httpd.conf: AddType application/x-miva-compiled .mvc
If you are setting up redirection (short-style URLs), add the following to your httd.conf: Action application/x-miva-compiled /cgi-bin/mivavm

Note: You can also set the Configuration individually for each of many individual sites by placing these variables, inside the VirtualHost blocks of the httpd.conf.

8. Set up Virtual Hosts, if you want to set up multiple MivaScript sites with independent configurations on one server:

- Note: Virtual hosts will run faster using this 4x Configuration, rather than the 3x configuration.
- use the Apache directive <VirtualHost> and enter the MvCONFIG_DIR_DATA and MvCONFIG_DIR_MIVA Environmental Variables (SetEnv) inside the <VirtualHost> block in httpd.conf. See Step 5.
- Set MvCONFIG_DIR_DATA and MvCONFIG_DIR_MIVA also at the root level.

Note: Apache and Zeus Web Servers: refer to the Miva Merchant Empresa VM 4.x UNIX Configuration Reference Manual for Redirection (short-style URLs) and, Aliases and Handlers (that must be configured on Zeus)

9. Refer to the Miva Merchant Empresa UNIX Configuration Reference Manual for information on the following:

- Additional Miva Merchant configuration variables, including timeouts, security flags, and others.
- The equivalent Miva Merchant configuration directives used in Miva Merchant Empresa 3.x and 4.x.

10. Test the installation.

- Place diag.mvcinto the HTML directory of a virtual host. (diag.mvcis a test program included in the mivaroot/directory of Miva Merchant Empresa VM distribution file.)
- You may then run the application using a URL similar to the following:

3x Server Safe Mode Installation

The Miva Merchant Empresa has the option of reading your current miva.conf and authfile.

1. Copy and rename mivavm-vx.xx.

1. Copy mivavm-vx.xx binary to the system-wide cgi-bin directory
  
  mivavm-vx.xx (the Miva Merchant Empresa VM binary) is located in the cgi-bin subdirectory of the distribution. (Refer to Distribution File Contents.)
2. Rename mivavm-vx.xx to mivavm.

2. Change the setuid permissions of mivavm binary. Enter the following commands directly at the server or via telnet:

chown root mivavm

chmod 4755 mivavm

Note: Changing the Miva Merchant Empresa VM binary file's setuid to the root, allows it to downgrade its permissions to the owner of the MivaScript application file.

3. Copy and rename 3x.so

1. Copy 3x.so to system-wide/cgi-bin.
  
  3x.so is a configuration file, and is located in the lib/config subdirectory of the distribution.
2. Rename 3x.so to libmivaconfig.so
  
  The Engine looks first in the current directory for the configuration library, libmivaconfig.so. (Alternatively, the MvCONFIG_LIBRARY environment variable could set the path. See the Miva Merchant Empresa UNIX Configuration Reference Manual.)

4. Copy or create the mivavm.conf configuration file.

1. If you have a miva.conf, copy the miva.conf file to the system-wide/cgi-bin, where the Miva Merchant VM binary is located, and rename it mivavm.conf.
2. If you do not have one, create one with any text editor. (See the Miva Merchant Empresa 3.9x UNIX Configuration Reference Manual for detailed information.)
  
  The name of the configuration file must be named the same as the Miva Merchant Empresa binary, with .conf appended.

Note: If you do not have an existing 3.x miva.conf, see the 3.x UNIX Installation and Configuration Reference Manuals for information on creating it.

5. Copy the lib/builtins and /certs directories. (See paths, in next steps.)

6. Enter a new tag into your mivavm.conf file for each of the built-in libraries.

To register the distributed built-in libraries, enter:

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/crypto.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/system.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/file.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/math.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/string.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/time.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/template.so">

<BUILTIN-LIB LIBRARY = "/usr/local/miva/lib/builtins/archive.so">

7. Enter these configuration directives into your mivavm.conf for OpenSSL files and certification files. These certificates are not secure URL certificates, the certificate folder is included in the distribution for the Virtual Machine. This does not refer to any other SSL or security certificates.

/usr/local/mivacerts/
openssl=/usr/local/miva/lib/libssl.so
openssl_crypto=/usr/local/miva/lib/libcrypto.so

8. Register a database library, enter a new tag into your mivavm.conf file for each library you want to register, in the form:

<DATABASE-LIB METHOD="type" LIBRARY="path">

To register a database library, enter, for example:



<DATABASE-LIB METHOD="mivasql" LIBRARY ="/usr/local/miva/lib/builtins/mivasql.so">

9. Many of the remaining configuration options (directives) and tags in your mivavm.conf files are the same as for Miva Merchant Empresa 3.9x, with some exceptions.

- <Package> tag is not supported
- See "3.x and 4.x Equivalents" in the Miva Merchant Empresa UNIX Configuration Manual for a list of supported configuration options.

3.x Standard Mode Installation

If your Web Host is Miva Merchant-enabled, you do not need to install Miva Merchant Empresa in your private cgi-bin.

If your Web Host is not Miva Merchant-enabled, you can install Miva Merchant Empresa only if you have a local private cgi-bin.

Standard mode can only be installed using the 3x configuration, and therefore, will not have certain configuration options available to it.

Place the Miva Merchant Empresa VM 4.x distribution file into a temporary directory, and change to that directory.
Gunzip or untar the binary, for example:
tar -xvf mivavm-vx.xx-platform.tar

Where x.xx is the version, and platform is the server environment
Locate your private cgi-bin directory. Your system administrator should be able to assist you.
Copy and rename mivavm-vx.xx.
- Copy mivavm-vx.xx from the temporary directory (where you put the distribution) to your cgi-bin (mivavm-vx.xx is located in the cgi-bin subdirectory of the distribution
- Rename mivavm-vx.xx to mivavm
Change the setuid permissions of the mivavm binary. Enter the following commands directly at the server or via telnet:

chown <myuserid> mivavm
chmod 4755 mivavm

Making the Miva Merchant Empresa VM 4.x binary setuid to your user id will ensure that the data files created by MivaScript applications will be owned by the specified user account.
Copy and rename the 3x.so configuration files.
- Copy the 3x.so file from the temporary directory (where you put the distribution) to your cgi-bin.
- Rename the file 3x.so to libmivaconfig.so.
Copy the lib/builtins directory (from the temporary directory where you placed the distribution) and its contents to your cgi-bin.
Copy the /certs directory (from temporary directory where you placed the distribution) and contents to your cgi-bin.
Copy or create the mivavm.conf configuration file in /home/user/cgi-bin/mivavm.conf.
- If you have a miva.conf, copy the miva.conf file to your private cgi-bin. And rename it mivavm.conf.
- If you do not have one, create one with any text editor. (See the Miva Merchant Empresa 3.9x UNIX Configuration Reference Manual for detailed information.)
Enter the following in your mivavm.conf.

Note: The "mivaroot" directory points to MivaScript directory and "stdmodedatadir" points to your Miva Merchant data directory. The cadir directory points to the certificates folder which is included in the distribution for the Virtual Machine

mivaroot=/home/user/mivahtml

stdmodedatadir=/home/user/mivadata

cadir=/home/user/certs

<BUILTIN-LIB LIBRARY = "/home/user/lib/builtins/system.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/builtins/crypto.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/builtins/file.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/builtins/math.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/builtins/string.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/builtins/time.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/template.so">

<BUILTIN-LIB LIBRARY = "/home/user/lib/archive.so">

Register a database library, enter a new tag into your mivavm.conf file for each library you want to register, in the form:
<DATABASE-LIB METHOD="type" LIBRARY="path">
To register a database library, enter, for example:
<DATABASE-LIB METHOD="mivasql" LIBRARY ="/usr/local/miva/lib/builtins/ mivasql.so">
Obtain the OpenSSL files, and place them in your /lib directory. For Miva Merchant users, some functions, services, shipping and payment gateways use OpenSSL.
- The OpenSSL files are libssl.so and libcrypto.so. Visit http://www.openssl.org, or obtain them from your host.
- Place libssl.so and libcrypto.so in your /lib directory.
Enter the path to your OpenSSL files in mivavm.conf.
openssl=/home/user/lib/libssl.so
openssl_crypto=/home/user/lib/libcrypto.so
After obtaining the Commerce Library or Libraries you require (for payment gateways, for example), place it (or them) in your /lib directory.
Enter the method, path and file name of your Commerce Library (or Libraries) in mivavm.conf. (Use separate entries for each library.) Refer to the Miva Merchant Commerce Libraries section in the Miva Merchant Empresa UNIX Configuration File Reference Manual.

<COMMERCE-LIB METHOD = "lib" LIBRARY = "home/usr/lib/lib.so">
Create an .htaccess file, or open your existing one.

In a text editor, add the following:
AddType application/x-miva-compiled .mvc
Action application/x-miva-compiled /cgi-bin/mivavm
Save .htaccess to your MivaScript directory. (Such as, /home/httpd/html.)
Test the installation. diag.mvc is a test program included in the mivaroot/ directory of the Miva Merchant Empresa distribution file. Place diag.mvc into the directory specified by mivaroot. You may then run the application using a URL similar to the following:

http://<your site>/<your private_cgi-bin>/mivavm?diag.mvc

Distribution File Contents

The contents and untarred directory tree of the Miva Merchant Empresa 4.x distribution file, miva-vx.xx-cgi-platform.tar(.gz) is shown below.


mivavm-vx.xx/
	cgi-bin/
			mivavm-vx.xx mivavm (link to mivavm-vx.xx) certs/
	lib/
		builtins/
			crypto.so math.so system.so file.so string.so time.so
		config/
			3x.so env.so
		commerce/
			<empty>
		databases/
			<depending on platform> oracle.so mivasql.so
	mivaroot/
		diag.mvc
	doc/
		RELNOTE.txt README.txt LICENSE.txt