
ANS (Avenger's News System) 2.1
Installation Document
-------------------------------

NOTES
-----
This won't work on web servers that run perl in tainted mode (for example,
Tripod).


HOW TO INSTALL
--------------

1.   Untargz ans-2.1.tar.gz
  a. If you are doing this on a UNIX box, type "tar -zxvf ans-2.1.tar.gz"
     in the directory where you downloaded the file to.
  b. If you are doing this on a Windows box, use WinZip to extract the stuff
     to a temporary directory.

2.   Configure internal variables
  a. Modify the first couple of lines in ans.pl to reflect the directory
     where you will be uploading this to. If you DON'T know, stop now and
     forget the entire thing. I suggest that you don't put these in a
     publicly accessable directory (although the password file is
     encrypted, it can still be cracked by somebody who's determined)

     $CONFIG_FILE = "/home/dude/ans/ans.config";
     $PASSWORD_FILE="/home/dude/ans/ans.passwd";

3.   Upload
  a. Make sure that if you're running a Windows system that you run
     ans.pl through something like DOS2UNIX. Many web servers will barf
     if it sees the extra CR/LF that DOS-based OS's put in there.
  b. Put ans.pl in your CGI-BIN directory somehow (cp if it's local, ftp
     if it's not) If you don't know where your CGI-BIN directory is, ask
     your sysadmin. You can't use this script if you can't use CGI. Chmod
     it 755.
  c. Put the remaining files (ans_data) in the directory you specified
     in CONFIG_FILE/PASSWORD_FILE. Chmod both the directory and the
     files 777. Make both a "messages" and an "include" directory under
     these, and chmod those 777 too.

3.   Configure dynamic variables
  a. Go to http://your.web.server/your.cgi.directory/ans.pl?p=admin.plugin
     and log in as "admin", password "fred" (case sensitive)
  b. Click on "Modify configuration file". Change the variables
     around to fit your system configuration and tastes. (Check out
     README.DynConfig for information on these variables). Change
     '<include dictionaries/english.dic>' to a different dictionary if desired.
  c. Click on "Modify a file" and enter 'dictionaries/english.dic' (or whatever dictionary
     file you're using) and change to your tastes.

4.   Change the admin password and create a new account
  a. Click on "Add new user". Enter applicable data for yourself and
     anybody else you want to give posting access to. Remember,
     passwords are case sensitive!
  b. Click on "Edit user file" and click on "admin". Change admin's
     password to something hard to guess. Once submitting, you'll have
     to re-login because the data bas changed.

5.   Customise HTML
  a. Click on "Modify template file". Enter your HTML code, putting a
     <PLUGIN>index.plugin</PLUGIN> where you want your news items to
     go. Submit.
  b. Click on "Modify Article Templates". Read the documentation at
     the top - if it still makes no sense, read it again. Enter
     your code and submit.

6.   Post a message
  a. Click "Post a Message". Enter the body of your message. Submit.
     Enter the subject to your message. Submit again.

7.   Enjoy
  a. Go to http://your.web.server/your.cgi.directory/ans.pl and look 
     around. Tweak to your tastes, and forward stuff from the entry
     to your main page to this URL. 

TROUBLESHOOTING
---------------
1.   I can't log in to the browser based admin
  a. Check to make sure you're typing admin in lowercase.
  b. Check to make sure that you uploaded ans.passwd to the same
     place that you specified in ans.pl.
  c. Alternatively, check to make sure that your browser supports
     cookies.
  d. If the web server is running some varieties of BSD, your system
     uses a different kind of implementation of crypt(). Shit, eh?
     Visit http://YOUR_WEB_SERVER/YOUR_CGI_DIRECTORY/ans.pl?crypt
     and change the garbage (encrypted password) in ans.passwd to the
     garbage that the web server spits out in return. Then login as
     l:admin p:admin
  e. Make sure your dictionary file actually exists and is readable.

2.   I don't see anything when I try to configure.
  a. You didn't upload the configuration files to the same place you
     specified in ans.pl.

3.   None of my changes are taking effect.
  a. Did you chmod the files to 777 (everybody read/write/execute)?

4.   I'm getting a 500 Server Error ...
  a. Change the #!/usr/bin/perl at the top of ans.pl to the path of your
     PERL interpreter. If your system doesn't have one, send a nasty
     message to your sysadmin.

5.   Something else is going wrong.
  a. Email me with a descriptive description of the problem.
     (problems@ans.gq.nu)
