LE CHAT Installation Guide

Last changed: 2018-01-06 for LE CHAT v2.0. Check the homepage for any updates of this guide or the script!

Server Requirements

Your server or (free-)hosting account just needs to support Perl CGI scripts. Some of the CAPTCHA modules require support for the GD library though, but there are also modules that will work on any restricted server configuration even. Read up on your server documentation how to enable Perl/CGI if it doesn't work already. On your own Apache server you can try adding those lines to your httpd.conf:

<FilesMatch \.cgi$> SetHandler cgi-script </FilesMatch>

To install GD.pm on a Debian-based system you can try these terminal commands:

sudo apt-get install libgd-xpm-dev sudo apt-get install libgd-gd2-perl

On Windows you can use a current ActivePerl package, which has the GD binaries compiled in already. Windows should be used for local testing only, I wouldn't recommend it for a public server! Make sure you read all the documentation and consider any security implications. Server security is a complex topic and you really must take it seriously before you should provide a public chat room. If you are a beginner, start with a private place and a few trusted friends only. Maybe invite a trusted tech guy who can check your server security first.

Edit the script file (optional)

There is just one line at the beginning of the script that you may want to change under certain circumstances.

my $datadir='./lcdat';

This is the data directory for all internal files of the chat, like members, sessions, etc. It's important that this directory is protected from web-access at all costs! The script tries to apply the correct chmod settings during initialisation already, but unfortunately this may have no effect on certain server configurations. If you run your own server, you may want to use something like '/var/lcdat' here. On a freehosting account that may not be possible, so make sure the directory will be protected from browser-access. The initialisation procedure will give you a possibility to check for that.

Upload lechat.cgi

This depends on your specific server setup, but most commonly you have to upload lechat.cgi into a special cgi-bin directory and change the chmod settings to 0711 (or maybe 0777 is needed) to make it executable. Check your server or (free-)hosting documentation for details. In rare cases it may even be needed to change the first line of the script to point to another Perl-interpreter. In case you want to quickly reinstall an existing chat on another server, you can also upload a lechat.txt file that contains all the backup data that you want to restore on initialisation (members, config, language).

Upload the CAPTCHA modules (optional)

If your chat is private, you probably won't need CAPTCHAs to keep bots out (though some can still be fun to use), but a public chat is definately prone to automated attacks. For LE CHAT it doesn't matter where you put the module files, as long as the lechat.cgi script is able to read the files. The location will be given to the script in the superuser setup screen later. Just put the modules directory as is into a sensible location and, like the data directory, make sure it's not accessible from the web. For the StoredImages-CAPTCHA you should create a directory that is readable from the web. It'll be used to serve temporary image files to the user.

As an example, I'll just assume that you put the directories from the zip-file as is in your web-root, the cgi-bin for the script files and the captchas directory for the temporary CAPTCHA images. Your directory structure will then look like this:

Some of the CAPTCHAs require additional Perl modules on your system, or your own customised settings and files to be useful. Read the comments in each LeCaptcha*.pm-file that you want to use, for further information!

Initialise The Chat

Call the script in your browser like this: http://(server)/(cgi-path)/(script-name).cgi?action=setup in our example that would be: http://your.domain/cgi-bin/lechat.cgi?action=setup If you get a 500 Internal Server Error, then recheck the chmod settings and possible requirements for the shebang-line (#!/usr/bin/perl). Once the script runs, you are guided through the setup process now, which should be pretty much self-explaining. Don't use your chatting nick for the superuser account or it will collide with the configuration setup later. Use a unique and secret nick instead. After you click "initialise chat" make sure you check the given links for the data directory and the admin file. If you don't get an error message (403 Forbidden), you must protect the directory yourself or edit the script file, as described above.

Next proceed to the setup page and set the server directories correctly. If this is your only chat, then leave the data directory blank. If this will be an additional chat, e.g. a staff room or a room for a different language, where you want to use the same members, then fill in the path to the already existing data directory of the main chat. The directory can be absolute (e.g. /var/lcdat) or relative to lechat.cgi (e.g. ../staffroom/lcdat).
The modules directory can be absolute or relative and should be ./modules in our example. The web directory for the temporary CAPTCHA images must be given relative to lechat.cgi and will be ../captchas here.
Click "save directory settings" to save your changes.

Now register yourself a main admin nick or restore a members file backup of your chat, unless you have set a shared members file with your admin nick present already. Older members files are still fully functional with v2.0. From now on you can use ?action=setup anytime to log in with your main admin nick to change the chat configuration. If you log in with your superuser nick you can still change the directories, your main admins or the language settings anytime.
Click "log out" to go to the admin login.

In case you translate the chat to a new language, please consider providing a copy for everyone else! Thanks in advance. :-)

Change The Configuration Settings

Use ?action=setup and log in with your main admin nick. You'll get access to all the chat configuration settings.
First thing you should do: Save the page as *.html and keep it somewhere, in case you mess up your CSS and HTML settings at a later point. If anything goes wrong, you can always look up the default settings at least.

Important: If there are multiple main admins in your chat, try not to edit the configuration at the same time. "save changes" will always overwrite the config file with your current settings on screen. This could become very confusing since your recent changes may mysteriously "disappear" if another admin is overwriting them at the same time. This issue will be addressed in a future version, though there should be no reason to edit the configuration very often by different admins.

Further explanation of some settings:

Use external link redirection script: If hotlinks are created, they will be redirected to a dereferrer page first to prevent leakage of the session-ID. If you also want to protect your (private) chat URL from leaking in the referrers, then you can setup another copy of this script on another server as a pure link redirector. For that, just set it to "link redirection only" at the top of the page in the Chat Setup.
Hours to remember guest logins: The nicks and passwords of new guests will be remembered for this number of hours to preserve their names and protect against imposters. If the same guest doesn't login again during that time frame, the name is released and can be reused by someone else. If session and message expiration added together is bigger, then that value will be used, because there could still be messages of that guest in the room.
Number of guests from which on to hide entry/exit and shorten list: If you have a lot of guests coming and going, the chatters list at the top of the messages and the entry/exit notifications can become very messy. If you set a value here, then the list of guests will be reduced to a number only and the entry/exit notifications omitted, once the number of guests in the room reaches that value.
Minimum time between posts from same nick (seconds): This is to prevent flooding of the chat. If a new message gets posted by the same nick before that time has passed, the message will be rejected. Only increase this value if it's really necessary.
CAPTCHA module to use: Here all the modules will show up if you have set the directory correctly in the superuser setup. "Show splash screen before login" and "Use CAPTCHA on splash screen" have to be activated for a CAPTCHA to show.
Content filters: If you are fluent in regular expressions, you'll love them. ;-) If not, check the page with helpful settings and content filters for examples you can copy and paste.
Background colour, Text colour, Link colour, Visited link colour and Active link colour: These are the default colours for the HTML <body>-tag. Even if you exclusively use CSS to style everything, make sure you set these colours according to your colour-scheme, since they are used for some internal HTML and CSS code and the readability check for randomised guest colours. Also browsers without CSS-support will be stuck with those colours for everything.
Any "CSS" fields: Put your CSS there as you would inside the <style></style>-tags.
Any "style" fields: Put your CSS there as you would inside the style="..." attribute of the element. Note: virtually every element has a class or id attribute, so you can just as well use the CSS-fields to style everything by its name. Examine the html-source to find the names.

See also Helpful Settings and Content Filters for some more tweaks and ideas!

Make backups!

Sounds trivial, but don't forget it! When you have changed all the settings to your liking, then save a backup of the configuration. If you mess up or a server-fault erases the file, you can restore all the work you put in. Same with the members, always make a fresh backup after you have registered new members and store the text in a safe location. Pro-Tip: Make a backup right at the beginning, before you even change anything. If you really screw up, you can then restore the basic default settings easily and start fresh.

Unsuspend The Chat Room

After you have saved your configuration, set the chat access to "enabled", so that you then can use the chat with the normal URL (without the ?action=setup). Otherwise you'll just get a suspended error page.

Open The Room For Guests

By default the room is closed for all guests. Log in to the chat with your main admin nick and click the "Admin" button. There you can open the room for guests now.

Questions, Problems, Suggestions?

If you have any feedback, please let me know and I'll update this guide as needed. A simple "Thank you!" is always appreciated as well. ;-)

Back to LE CHAT