From . .. poMMo .. .
NOTE: This document is for poMMo versions PR11 and above. If you are trying to install or upgrade to Aardvark PR10.2 and below, see our Old Install Guide.
- Upgrade Instructions -> If you are upgrading poMMo (and not installing from scratch) see our Upgrade page.
Quick Install Guide
- Following is a summary of the installation process that can be used as reference by those familiar with this process.
- Make sure your webhost meets the Minimal Requirements
- Download and extract the latest version of poMMo
- This should create a directory named 'pommo' wherever you unpacked it. This is known as the poMMo Root.
- Create the config.php in your poMMo Root
- Save the included config.sample.php as config.php and use it for reference.
- Create a MySQL database on your webserver for poMMo to use.
- Make sure the database name, host, and username/password match the values provided in config.php
- If you have not done so already, copy the entire contents of the poMMo Root to the directory you'd like poMMo to run from on your webserver.
- You can use FTP to install poMMo on your webserver
- Make sure the webserver can write to the "cache" directory in the poMMo root.
- This can be accomplished by setting permissions to "777" on a *nix system.
- Visit your poMMo installation in a web browser and complete the online install procedure.
Your webserver must have the following installed and running
- PHP 4.3.2 or higher
- Apache Timeout directive or IIS CGI timeout should be 100+ seconds (both default to 300)
- For i18n (other languages) PHP should have gettext support
- MySQL Server 4.1.11 or higher (or 3.23 for Legacy poMMo)
- Before installing, make sure your webserver meets the Minimal Requirements. poMMo is designed to be highly portable, and 99% of webhosts will meet its needs. If you are unsure, contact your web provider.
- If you need help installing poMMo, you can visit our Support page for help, or ask for paid assistance from the Services page.
Download and Extract poMMo
- Get the latest version of poMMo from the Downloads page. Once you have downloaded the program, you will need to extract it. poMMo comes in either a "zip" file, or a "tar.gz" file (smaller). Programs such as TugZip, WinZip, and the Windows XP Archiver can "extract" the program. If using Linux, download the .tar.gz file and extract it with "tar -xvfz [filename]".
Gather Database Information
- poMMo requires a database to run; it provides fast and efficient storage for subscriber and configuration data. Make sure your webserver has access to a MySQL database. Contact your web host for details. Ask them for the 'hostname', username', 'password', and 'database name' of a MySQL server you can use.
- NOTE: poMMo can exist in a shared database. You can also have multiple installations of poMMo using the same database by changing the table prefix.
- Write down your MySQL database information.
- poMMo's configuration is loaded up from a file named "config.php" in the poMMo Root. This file tells poMMo how to connect to the database, what language to use by default, and set debugging options. You need to create this file. A sample configuration file named "config.sample.php" is included in the poMMo Root for reference.
- After extracting poMMo, it will create a directory named "poMMo". This directory is known as your poMMo Root. Navigate into this directory and edit "config.sample.php" with your favorite text editor. If using Windows, right click the file and click "edit" or open with->Notepad. If using *NIX/BSD, try "pico" or "vi" as a shell editor.
- Save config.sample.php as "config.php" in the same directory. Follow its instructions for setting database and language values.
- poMMo runs from your webserver. Its files must be copied to the webserver and placed in a directory accessible from the web.
- Use FTP or your preffered method to copy the poMMo files from your machine to the directory you'd like poMMo to run from on the webserver. For example; If the website you'd like to use poMMo with is located at '/home/b/brice/public_html/companyX' on your webserver, copy the poMMo files (including the config.php file you made) to '/home/b/brice/public_html/companyX/poMMo' -- You should now be able to access poMMo by visiting http://www.companyX.com/poMMo/.
- You can name the poMMo Root anything you'd like. For instance (in the example above), if you copied the files to /home/b/brice/public_html/companyX/newsletter/, you could access your mailing list by visiting http://www.companyX.com/newsletter/.
Set Permissions on Cache Directory
- After placing poMMo on your webserver, you must make sure that the webserver can write to the cache directory. By default, the cache directory is located in the poMMo Root as cache. poMMo uses this directory to store compiled template files for speed, and will not work if the webserver can not write to it. You can test if your webserver can write to this directory by visiting your poMMo installation from a web browser. It will complain that it can't write to the cache directory if the permissions are incorrect.
- To set proper permissions on the cache directory, you can ask your web provider to allow the webserver to write to the "cache" directory, or you can set them yourself. Execute 'chmod 777 cache' from poMMo Root on a Linux system. Some FTP clients allow changing of permission also. Ensure that Owner, Group, and Other have write access to cache.
- If you'd like to change the location of the cache directory, you can do so by editing config.php and modifying the "bm_cacheDir" parameter. It is recommended to set it somewhere outside the webroot for security reasons (so that it's files cannot be directly accessed from the web).
SAFE MODE Users; Manual setup of Cache Directory
- If you're using PHP Safe Mode, you will have to manually setup the cache directory. To do so, Enter the cache directory. If the cache directory contains a directory named "pommo", delete it and all subdirectories under it*. With a clean cache directory, create a directory named "pommo". Set permissions so that the webserver can write to it ("chmod 777 pommo"). Create another directory inside "pommo" named "smarty". Set permissions so that the webserver can write to smarty. Your work directory should now look something like;
/path/to/pommo/cache/pommo (webserver writable) /path/to/pommo/cache/pommo/smarty (webserver writable)
- NOTE: You may not be able to delete the "pommo" directory due to permissions. To get around this, visit support.php (e.g. http://www.yourdomain.com/yoursite/pommo/support.php), and click "clear work directory".
- Visit your poMMo installation on the web. If all goes well, you will be presented with an installation page. Provide the administrator's passowrd and site details. The online installation script will take care of the rest. You are now ready to setup your list. It is recommended to familiarize yourself with Demographics, Groups, and the Subscriber Form.
- Cache Directory: poMMo uses this directory to save compiled template files, and will not work if the webserver cannot write to it. By default, the cache directory is located in the poMMo root directory, and named cache. You can change its location by modifying the bm_workDir parameter in config.php.
- poMMo Root: The "main" directory of your poMMo installation. When you first extract poMMo, it creates a directory named "pommo" containing the program's files. This is your "poMMo Root". It holds your configuration file (config.php), as well as other folders (such as "admin", "themes", and "language") which the program is organized into. You can rename this folder to anything you'd like. For instance, from "pommo" to "newsletter".
- FTP: Stands for "file transfer protocol" and has become the standard method of transfering files to machines on the internet. Modern web browsers (IE/Firefox/Opera) have FTP built into them. You can also use a standalone client such as SmartFTP and FileZilla.
- Shared Database: Some web providers provide 1 MySQL database per account. Any program that uses a database must then share the single one. This is OK, because most programs save their data in specific "tables" (sections of the database), and will not interfere with the data of other programs using the same database.
- Table Prefix: poMMo accomplishes a peaceful existence in a [Shared Database] through the use of a "table prefix". You can change the table prefix from the config.php file, so that you can have multiple installations of poMMo running from the same [Shared Database]. Make sure that each installation of poMMo has a unique table prefix if they are to use the same database.
- Webserver: This is your "web host", and is the computer that runs poMMo. Most webservers are running "Apache" (If they're Unix/Linux/BSD), or "IIS" if they're Microsoft Windows.
- Provided is a sample config.php file. A simplified config.php file can be seen below
<?php die(); /* DO NOT REMOVE THIS LINE! SERIOUS SECURITY RISK IF REMOVED! */ ?> ==================================================================== Welcome to the poMMo Configuration File! From here you setup your database and other preferences. IMPORTANT: This file must be named "config.php" and saved in the "root" directory of your poMMo installation (where bootstrap.php is). See config.simple.sample.php for a condensed, readable config file. ==================================================================== ::: MySQL Database Information ::: [db_hostname] = "localhost" The MySQL Server poMMo will connect to (usually localhost) NOTE: Remote MySQL servers (e.g. mysql.yourwebhost.com) can be used. [db_username] = "brice" The username poMMo will use to login to MySQL server [db_password] = "1234" The password poMMo will use to login to MySQL server [db_database] = "pommo" The name of the MySQL Database poMMo will use [db_prefix] = "pommo_" Change if you intend to have multiple poMMos running from the same database ::: Language Information ::: [lang] = en Set this to your desired locale. Current languages available are; bg - Bulgarian it - Italian da - Danish nl - Dutch de - German pt - Portuguese en - English pt-br - Brazilian Portuguese en-uk - British ro - Romanian es - Spanish ru - Russian fr - French ::: Optional Configuration ::: ==================================================================== Below Options are intended for debugging or overriding automatic configuration. ==================================================================== [debug] = off Enable (on) or disable(off). Debug mode is useful for providing information to developers [verbosity] = 3 Set the logging verbosity level. 1: Debbuging mode - *EVERYTHING* is outputted. 2: Informational mode - *MOST EVERYTHING* is outputted 3: Quiet mode - *IMPORTANT THINGS* are outputted [default] [date_format] = 1 Set the preferred date format. Available formats are; 1: YYYY/MM/DD (e.g. 1969/12/15) [default] 2: MM/DD/YYYY 3: DD/MM/YYYY ::: Overrides ::: Uncomment (remove the leading "**") to define the following settings. NOTE: These settings are auto-detected by default, and best left unchanged. ** [baseURL] = "/mysite/newsletter/" Set the Base URL (poMMo's path relative to the webserver) e.g.; (poMMo location) (baseURL value) http://newsletter.mysite.com/ / http://www.mysite.com/me/pommo /me/pommo/ NOTE: Include trailing slash ** [workDir] = "/path/to/pommoCache" Set the "working" directory. poMMo writes files to this directory. By default, it is set to the "cache" directory in the poMMo root. For increased security move this directory to a location not reachable via the web (e.g. /home/brice/work vs. /home/brice/public_html/work) Make sure the webserver can write to this directory! ** [hostname] = www.mysite.com Set the webhost's server name ** [hostport] = 8080 Set the webhost's listening port [Usually 80, 443, or 8080]
- Simplified sample version of config.php
<?php die(); /* DO NOT REMOVE THIS LINE! SERIOUS SECURITY RISK IF REMOVED! */ ?> ========================================================== Welcome to the poMMo Configuration File! From here you setup your database and other preferences. IMPORTANT: This file must be named "config.php" and saved in the "root" directory of your poMMo installation (where bootstrap.php is). See config.sample.php for descriptions of settings ========================================================== [db_hostname] = localhost [db_username] = brice [db_password] = 1234 [db_database] = pommo [db_prefix] = pommo_ [lang] = en [debug] = off [verbosity] = 3 [date_format] = 1 The following are auto-detected, and are best left commented out. ** [workDir] = "/path/to/pommoCache" ** [baseURL] = "/mysite/newsletter/"; ** [hostname] = www.mysite.com ** [hostport] = 8080 ** [subscriber_default_sort] = email