PREREQUISITES

In order for OpenACH to function properly, the following software must first be installed:

• Apache 2.2 or higher
• PostgreSQL 9.1 or higher
• PHP 5.3 or higher (both Apache module and CLI)
• Yii Version 1.1.14 or higher
• PHP PostgreSQL, MCrypt and CURL modules
• PHP Extension (PECL) DoubleMetaphone (http://pecl.php.net/package/doublemetaphone)

On a stock Ubuntu 12.04 LTS system (or similar), the prerequisites can be installed with the following:

# sudo apt-get install postgresql-9.1 postgresql-common \
       apache2 php5 php5-cli php5-mcrypt php5-pgsql php5-curl \
       build-essential php5-dev php-pear
# sudo pecl install doublemetaphone
# echo 'extension=doublemetaphone.so' | sudo tee /etc/php5/conf.d/doublemetaphone.ini

Installing OpenACH Code Base

Development Version

To install the latest development version, you can use Subversion to export from the source repository on Assembla:

# svn export http://subversion.assembla.com/svn/openach/trunk /home/www/openach

To install a slightly more stable development version, you can use the latest development branch release tag from the source repository on Assembla:

# svn export http://subversion.assembla.com/svn/openach/tags/ /home/www/openach

Production Version

To ensure that the latest production fixes are in place, using Subversions, export the latest stable release tag from the source repository on Assembla.

# svn export http://subversion.assembla.com/svn/openach/tags/ /home/www/openach

Set Permissions

The web server needs to be able to write to just two directories, and needs only read access to the rest.

# chmod 777 /home/www/openach/protected/runtime/

OR using setfacl (ACL rules)

# setfacl -m u:www-data:rwx /home/www/openach/protected/runtime/

# chmod 777 /home/www/openach/protected/runtime/

OR using setfacl (ACL rules)

# setfacl -m u:www-data:rwx /home/www/openach/assets/

Apache Web Root

As with any PHP web application, you will need to configure Apache to point a DocumentRoot where your OpenACH folder is going to live. For this example we will use /home/www/openach/. Edit your apache configuration file(s) to ensure that /home/www/openach/ is available on your web server. Also set AllowOverride to all, as OpenACH needs it to allow rewriting of URL paths. A quick an easy way to get this done is to use the distributed Apache site config file, located in protected/data/etc/apache2/sites-available/openach:

# cd /home/www/openach/protected
# sudo cp data/etc/apache2/sites-available/openach /etc/apache2/sites-available/
# sudo a2ensite openach
# sudo a2enmod php5 rewrite
# sudo service apache2 restart

Installing/Upgrading Yii

The OpenACH platform is built on top of the Yii framework. It is recommended that you set up your install to make it easiest to upgrade Yii separately from OpenACH. You will notice the symbolic link named yii inside the OpenACH installation folder. By default this is configured to point to /home/www/yii, so that is the simplest place to install the Yii framework. The instructions below are for the 1.1.14 version of Yii, but you should download the latest Yii release from www.yiiframework.com, and install it following the pattern below:

# cd /home/www/
# wget https://github.com/yiisoft/yii/releases/download/1.1.14/yii-1.1.14.f0fee9.tar.gz
# tar zxvf yii-1.1.14.f0fee9.tar.gz
# ln -s yii-1.1.14.f0fee9 yii

Database Setup

OpenACH has been tested on both PostgreSQL 9.x and SQLite 3.x. If you are doing very large volumes of transactions, you will likely benefit from running a dedicated PostgreSQL server - possibly even multiple servers with replication. For most uses, including small to medium production installs, development and test-drive installs, you may want to consider using the SQLite option.

SQLite

SQLite support was introduced in OpenACH 1.2. To set up SQLite, ensure that you have the SQLite3 packages installed. On an Ubuntu 12.04 LTS (or equivalent) system this can be accomplished as:

# sudo apt-get install sqlite3 php5-sqlite

Next, make sure you either create a new database file, or use the distributed SQLite template database.

Create a New DB from the Schema

# cd /home/www/openach/protected/
# sqlite3 -init data/schema.sqlite.db runtime/db/openach.db .exit

Use the Distributed Template DB

# cd /home/www/openach/protected/
# cp data/openach.db.init_save runtime/db/openach.db

Set File Permissions

The SQLite database file needs to be readable and writable by both the web server process and the system user that will be maintaining the OpenACH platform.

# cd /home/www/openach/protected/
# chown www-data:openach runtime/db/ runtime/db/openach.db
# chmod 770 runtime/db/
# chmod 660 runtime/db/openach.db

Alternatively, if you have ACL installed on your server:

# cd /home/www/openach/protected/
# setfacl -m u:www-data:rwx runtime/db/
# setfacl -m u:www-data:rw runtime/db/openach.db

PostgreSQL

Next we will create a new PostgreSQL user for OpenACH to use. Run the following command as the PosgreSQL user (postgres)

# sudo -u postgres createuser openach
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n

Create a new PostgreSQL database for OpenACH to use:

# sudo -u postgres createdb openach -O openach
# sudo -u postgres psql -U postgres -d postgres -c "alter user openach with password 'QWERTY';"

Initial Configuration

All OpenACH configuration files are located in protected/config/. There are a few files you will need to edit in order to get the platform up and running for the first time: db.php (for the database connection info), security.php (for the encryption keys). You may also want to look through console.php (used for command line operations), and main.php (used for web app operations).

Database Configuration

SQLite

Update db.php to point to your SQLite database:

		return array(
                        // NOTE!!!  The URI must contain the ABSOLUTE path to the SQLite DB
                        'connectionString' => 'sqlite:/home/www/openach/protected/runtime/db/openach.db',
                        'emulatePrepare' => true,
                        'initSQLs' =>array( 'PRAGMA foreign_keys=ON;' ),
		);

PostgreSQL

Update db.php both with your PostgreSQL database, username and password that you created in the previous step:

		return array(
                        'connectionString' => 'pgsql:host=localhost;port=5432;dbname=openach', // Update with your db name
                        'emulatePrepare' => true,
                        'username' => 'openach', // Update with your db username
                        'password' => 'QWERTY', // Update with your db password
		);

Security Configuration

You will also want to initialize the security key that will be used to encrypt the data. It is very important that this key be kept secret, and a backup copy stored in a safe location. If for some reason you were to lose the key, it would be impossible to recover any data from your database. A simple way to come up with a secure key is to use the sha512sum command run on a random file of your choosing:

# openssl rand 2048 | sha256sum | cut -d ' ' -f 1
b47fe25331e4d6ffa5935bb5b078db82659aedf96ee29beeb1af992c2eabebcc

For added security, you can modify several characters in this hash. It could be a random phrase, the current wind speed and temperature, or anything else you like.

        O  p    e    n    A    C  H   i   s   c   o  o   l  !!
b47fe253O1epd6ffe5935nb5b0A8db8C65Haedi96es29bceb1of9o2c2lab!!cc

Do this process twice using two different files to come up with both an encryption key as well as a validation key. Then edit the security.php file in the config directory, updating the encryptionKey and validationKey accordingly. WARNING!!! It is vital that you have a backup copy of this information, as without it, your OpenACH data will become useless. There is no way of recovering these keys if they get lost. You have been warned. Then take this string and use it as your security key:

                retur array(
                        'cryptAlgorithm' => 'rijndael-256',  // This is AES-256
                        'encryptionKey'  => 'b47fe253O1epd6ffe5935nb5b0A8db8C65Haedi96es29bceb1of9o2c2lab!!cc',
                        'hashAlgorithm'  => 'sha1',
                        'validationKey'  => '0f27bd03b423eb9ff05d6e1bb415d2c5c553bed0808b3de8fd32306c4feb3313',
                );

Loading the PostgreSQL Database

NOTE: If you are using SQLite, you may skip this step and proceed to Using the Command Line Utilities. OpenACH comes with a setup utility, provided as a Yii command line action. You can use this utility to load the distributed schema file and data file, located in the protected/data/ folder. The setup utility can be run as follows:

# cd /home/www/openach/
# cd protected/
# ./yiic setup run --schema_file=data/schema.postgresql.sql --data_file=data/data.postgresl.sql --test_only=1

You will be met by a warning that you can bugger things up. We just want to make sure you know exactly what you're doing here. Verify your DB connection string is correct, and then add the confirmation option to the command line:

# ./yiic setup run --schema_file=data/schema.postgresql.sql --data_file=data/data.postgresql.sql --test_only=1 --confirm="fresh install"
NOTICE!!!  Running in test only mode - rolling back the transaction.
If you are seeing this message, no errors occurred.  It should be safe to commit the changes using the "--test_only=0" option.

Note that at this point, it is still in test-only mode, meaning the setup utility will not commit any database changes. This gives you a chance to make sure the schema and data is going to load properly. When you are confident that everything is going to go as planned, change the --test_only option to 0, and you'll be on your way:

# ./yiic setup run --schema_file=data/schema.postgresql.sql --data_file=data/data.postgresql.sql --test_only=0 --confirm="fresh install"
The SQL was successfully committed to the database.

Using the Command Line Utilities

In the previous step we used a Yii command line utility to load the schema and populate the core data. Several other command line utilities are available for managing all the aspects of OpenACH. To see a list of commands, run ./yiic in the protected folder:

# cd /home/www/openach/protected/
# ./yiic
Yii command runner (based on Yii v1.1.12)
Usage: ./yiic  [parameters...]

The following commands are available:
 - altbatchbuilder
 - apiuser
 - bankplugin
 - batchbuilder
 - confirmationprocessor
 - cronnightly
 - encryptionutility
 - externalaccount
 - fedachupdate
 - filebuilder
 - hashindexer
 - message
 - migrate
 - ofacupdate
 - paymentprofile
 - paymentscheduler
 - phoneticindexer
 - profilesimulator
 - returnchangeprocessor
 - setup
 - shell
 - user
 - webapp

To see individual command help, use the following:
   ./yiic help 

To get help on a specific command, use the help action:

# ./yiic help user
Usage: ./yiic user 
Actions:
    create --user_login=value --user_password=value --user_email_address=value --user_first_name=value --user_last_name=value
    changePassword --user_login=value --user_password=value
    view --user_id=value
    disable --user_id=value
    enable --user_id=value
    setup --user_id=value --name=value --identification=value --routing_number=value --account_number=value

Initializing Third Party Data

NOTE: If you copied the distributed SQLite database file, you already have this data loaded. However, as there may be updates from time to time, you will want to reload this data before using in production. OpenACH relies on a few third party data sources to populate its FedACH and OFAC-related tables. Thanks to the command line interface, loading and refreshing this data is simple: First, load the FedACH directory:

# ./yiic fedachupdate reloadAll
Opening file http://www.fededirectory.frb.org/FedACHdir.txt for import.
Parsing file... (this may take a moment)
Processed 20019 lines.
Saved 20019 records.
Opening file http://www.fededirectory.frb.org/fpddir.txt for import.
Parsing file... (this may take a moment)
Processed 8694 lines.
Saved 8694 records.

Now load the OFAC lists (note this may take some time as it will do lots of phonetic indexing):

# ./yiic ofacupdate reloadAll
Opening file http://www.treasury.gov/ofac/downloads/sdn.ff for import.
Parsing file... (this may take a moment)
Processed 5738 lines.
Saved 5738 records.
Opening file http://www.treasury.gov/ofac/downloads/alt.ff for import.
Parsing file... (this may take a moment)
Processed 6855 lines.
Saved 6855 records.
Opening file http://www.treasury.gov/ofac/downloads/add.ff for import.
Parsing file... (this may take a moment)
Processed 10473 lines.
Saved 10473 records.

Create New User

Once you have successfully installed OpenACH, the first step to a functional system is to create a user under which origination accounts can be set up.

# ./yiic user create --user_login=johndoe --user_password=supersecret [email protected] --user_first_name=John --user_last_name=Doe
Creating new User...
User: 
	User ID:		ced64f44-1959-443d-a38f-0178f650050d
	Login:			johndoe
	First Name:		John
	Last Name:		Doe
	Status:			enabled

Setup Origination Account

This new user can't do much without an origination account. You could use the web interface to set up each piece individually, but its much quicker to use the user setup utility. Note that you will need to specifiy the User ID generated from the previous command. Identification should be an EIN (Tax ID) for the business through which they are setting up the origination account. The routing number and account number are for the origination account at the bank where it was set up. Feel free to use the sample values below for now if you would like to just try things out.

# ./yiic user setup --user_id=ced64f44-1959-443d-a38f-0178f650050d --name="Test Originator" --identification=112358130 --routing_number=101000187 --account_number=1234567890
User: 
	Originator:		0e69c027-a9d4-466c-9f89-bbc47c8eb771
	Originator Info:	c38b6230-f8c9-45dc-9a86-5a32bc8d60d8

If all goes well, you will get an ID for the Originator (the legal parent entity) and the Originator Info (a particular origination account at a particular bank). It also created a Settlement Account, some Payment Types, and other odds and ends for you. If you log into your web account

Where to Go From Here

At this point, you have an origination account set up and ready to add payment profiles and payment schedules. You can log into OpenACH by pointing your browser at the server where you have it installed (http://localhost/ for instance). Follow along with some of the video tutorials and you'll be processing payments in no time.

Integrating with OpenACH

If you have other systems that you want to use with OpenACH, adding payment processing to existing or new applications, integration with a website, etc., you will want to set up an API user for the origination account that you created above. NOTE: The UUIDs used below should be replaced with the ones you saw when setting up your user in the steps above.

# ./yiic apiuser create --user_id=ced64f44-1959-443d-a38f-0178f650050d --originator_info_id=c38b6230-f8c9-45dc-9a86-5a32bc8d60d8
Creating new API User...
API User: 
	User ID:		ced64f44-1959-443d-a38f-0178f650050d
	Originator Info ID:	c38b6230-f8c9-45dc-9a86-5a32bc8d60d8
	Api Token:		veMnAoCAaPJr9NUmJ9KkD2Oz5hO3rY70A1VSnc1mBq2
	Api Key:		eTqgmbqukjEs13V942heirDxmWbKNnJgAcocvJ4wCGN
	Status:			enabled