# Parley - Setup Guide

## Table of Contents

1. Getting Parley
2. Initial Deployment

1. Location
2. Extract
3. Database
4. Local Configuration
5. Testing

3. Launching the Application
4. The Email Engine
5. Using Parley

- Site Usage Terms
- Site Administration

- services
- users
- ip bans

- Additional User Administration

6. apache + fastcgi

- configuring fastcgi
- troubleshooting fastcgi

- Permission Denied
- Unable to store upload

7. Further Information

## Getting Parley

You should get Parley by visiting the project page at BerliOS or from the author's CPAN page

## Initial Deployment

### Location

For the purposes of this guide we are assuming that there is a user called "parley" [HOME=/home/parley/] who has never deployed the application previously.

We'll keep as much of parley as possible inside its own directory area:

> `mkdir -p ~/parley_app/{dist,versions,user_files} cd ~/parley_app/`

We'll use `dist/` to store any tarballs that we have downloaded, to reduce clutter:

> `mv /.../Parley-1.x.y.tar.gz dist/`

### Extract

Then extract our most recent copy [the only one currently]:

> `tar -C versions/ -zxf dist/Parley-1.x.y.tar.gz`

Making a softlink to the current version makes navigation easier, and will aid us later when we consider a full Apache based deployment:

> `ln -sv versions/Parley-1.x.y parley ln -sv $PWD/user_files parley/root/static/user_file chmod -R g+w user_files cd parley`

To prevent permission errors later on, you should ensure that the user that runs the apache processes is in the parley group.

### Database

Before we can run the application we need to setup the database:

> `sudo -u postgres createuser -A -d parley createdb -U parley -E UTF8 parley psql -U parley -d parley -f db/parley.psql`

We can quickly check that we have created something:

> `psql -U parley -d parley -c '\dt'`

### Local Configuration

There are some supplied configuration options that you may wish to override. The recommended method for doing this, and one that will preserve your changes after any application updates are as follows:

> `cd ~/parley_app/ vim parley_local.conf`

Add entries to this file. They will take precedence over values in `parley.conf` The following are examples of common areas requiring local overrides.

#### name

It's likely that you will want to use a name other than Parley for your deployment.

> `name Company Discussion`

#### recaptcha

reCAPTCHA is a great way of making sure you have humans (not bots, or scripts) signing up for your copy of Parley. It's disabled by default because you'll need a (free) key-pair for the domain you intend to use it on.

You can sign up and generate reCAPTCHA keys at recaptcha.net

> `<recaptcha> enabled = 1 pub_key = 6Lem123456789012345678901234567890123456 priv_key = 6Lemabcdefghijklmnopqrstuvwxyzabcdefghij </recaptcha>`

#### google_adsense

You may wish to have some ads shown in your application. This is disabled by default because you'll undoubtedly want to provide your own adsense configuration, not the developer's.

> `<google_adsense> enabled = 1 # default language for ads google_language = "en"; # your adsense identifier google_ad_client = "pub-1234567890123456"; <ad728_90> # 728x90, created 22/04/09 google_ad_slot = "1234567890"; google_ad_width = 728; google_ad_height = 90; </ad728_90> </google_adsense>`

### Testing

Although coverage isn't as high as desired, it makes sense to run the application tests to make sure there are no show-stopping issues:

> `PARLEY_DEBUG=0 prove -lr t/`

All test should pass. If they don't you may run into problems when using the application:

> `All tests successful, 2 tests and 169 subtests skipped. Files=44, Tests=455, 54 wallclock secs (38.13 cusr + 2.59 csys = 40.72 CPU)`

## Launching the Application

Assuming that the tests passed, you should be in a position where you can run and explore the application.

Although not recommended for a production deployment you can run the application for testing and evaluation using `script/parley_server.pl`.

In its most simple form you can start the application with:

> `script/parley_server.pl`

If there are no problems you should see something similar to:

> `[info] Parley powered by Catalyst 5.7012 You can connect to your server at http://localhost:3000`

View the URL in your browser and you should see the Forum List page with three forums listed.

### Running under apache

This is described in greater detail later in this document. At this point in the process we just want to run the application and explore it a little.

## The Email Engine

Parley emails will only be sent if the email engine is running. The email engine is a stand-alone script that is launched and runs in the background.

It polls a table for emails that need to be sent and performs the required magic to send them.

BEFORE you start the email engine, please edit `parley.conf` and edit `from_name` and `from_address` in the `alerts` section.

You can start the email engine with:

> `./script/parley_email_engine.pl`

Because the script puts itself into the background you won't see any output in your terminal. You can verify that the script is running by doing the following:

> `ps ax |grep parley_email`

and you should see something similar to:

> `18061 ? S 0:00 perl ./script/parley_email_engine.pl`

The email engine uses syslog to log messages, which means you may be able to see further information in `/var/log/messages`:

> `$ grep parley_email_engine /var/log/messages Apr 21 19:07:26 wiggin parley_email_engine[18058]: script started Apr 21 19:07:26 wiggin parley_email_engine[18061]: child process created`

## Using Parley

There isn't much you can do in a forum with no messages. Parley comes with two users out of the box: Top Dog, an application super-user, and Normal Normal, a user with no special powers at all.

Top Dog's username is `topdog` and has a default password of `k1tt3n`.

Norman's username is `norm` and also has a default password of `k1tt3n`.

Both users can post, read posts, search, browse, etc. Top Dog also has access to the Site menu in the menu-bar.

### Site Usage Terms

One of the first tasks you may like to perform as Top Dog is adding T&Cs for the site. If Parley has T&Cs defined all registered users must agree to those terms to continue using the site. ('Guest' users can use the site in read-only mode without needing to agree to the T&Cs).

If new T&Cs are added, users must agree to those to continue uing the site.

You can add new T&Cs by clicking the Add T&Cs item in the Site menu.

### Site Administration

As a site moderator you will have access to the "Site→Manage" menu.

This is the primary area for checking on the status of services, managing users and also various ban types

#### Services

Lists known services (currently only the email-engine) and their current status

#### Users

This section currently provides role-management functionality. It's functional, but in the early phases of development - which means it could be nicer to use.

Select the user you'd like to manage by typing the first part of their name in the User Search field, then selecting the correct menu item, and submitting the query.

You'll be presented with a list of roles and checkboxes. Select and unselect the options to your heart's delight

Note: you are not able to remove your own "Site Moderator" role. Other site moderators can do it to you, you can do it to them. Unless my brain is broken this means you'll always have a minimum of one Site Moderator.

#### IP Bans

Unfortunately there will always be at least one bad apple. The IP bans are one tool in your battle against the Bad Ones. Banning by IP isn't a silver bullet for numerous reasons but it can stop or slow down some abusers.

Click on the data area for the type of ban you'd like to edit and edit the values in the text input area that appears. The items in the list should be in CIDR format (a.b.c.d/x) format.

To remove bans, edit the field and remove the relevant entry.

The anticipated escalation level for bans is: posting, sign-up, login, all

### Additional User Administration

Providing you have the required roles you will be able to perform additional tasks from a user's profile page: Suspend Account and Forum Moderation.

## apache + fastcgi

Any vaguely sane deployment of parley will not be run using script/parley_server.pl.

A common (and Catalyst recommended) deployment method is to use apache + fastcgi. The process is outlined in the Catalyst Cookbook

Before going too far down this route, please ensure that you have mod_fastcgi installed:

> `sudo aptitude install libapache2-mod-fastcgi`

### Configuring fastcgi

To avoid permission issues with certain files it's recommended that you edit parley.conf and change:

> `COMPILE_DIR /tmp/parley-ttcache # ... storage /tmp/parley.session`

to:

> `COMPILE_DIR /tmp/parley-fastcgi.ttcache # ... storage /tmp/parley.fastcgi.session`

Assuming you have a system with a2ensite installed on it you can do the following:

> `sudo cp config/parley.sites-available /etc/apache2/sites-available/parley.named_vhost sudo vim /etc/apache2/sites-available/parley.named_vhost # make appropriate changes sudo a2ensite parley.named_vhost sudo /etc/init.d/apache2 reload`

If all went well, you should now be able to visit the VirtualHost defined in /etc/apache2/sites-available/parley.named_vhost and find a working instance of Parley.

### Troubleshooting fastcgi

#### Open of share file /tmp/parley.session failed: Permission denied

Sometimes the fastcgi processes fail to start, and raise an error similar to:

> `Open of share file /tmp/parley.session failed: Permission denied at /usr/lib/perl5/Cache/FastMmap.pm line 574.`

This is usually caused by running the application as one user, then later trying to run it as a different user. The second user will usually discover that they don't have write access to the application session file.

There are a number of resolutions for the issue:

- remove /tmp/parley.session and parley-ttcache
- make the files world-writable
- make the files group-writable, and put relevant users in the relevant group

#### Failed to create destination directory. Unable to store upload.

If you see the above message when trying to upload a user avatar it's usually a result of incorrect permissions. You will usually have a corresponding message in the apache error log:

> `/home/parley/parley_app/versions/Parley-1.0.0/root/static/user_file/0 - Permission denied`

This can be resolved (as can most file permission issues) in more that one way.

NOTE: because of the way the application was deployed the "offending" directory is `parley_app/user_files/`

which we linked to as `parley_app/versions/Parley-1.0.0/root/static/user_file`.

One solution is to make the directory group-writeable and add the apache process owner to that group:

> `cd ~/parley_app/ chmod -Rv g+w user_files sudo usermod -a -G parley www-data groups www-data`

## Further Information

Please direct any further questions to the Parley user's mailing list.