added 1.02 codebase

README.txt

@@ -0,0 +1,181 @@
+webDiplomacy readme, for webmasters
+----------------------------------------
+=> Note to players
+=> requirements
+=> Installing
+=> Updating
+=> Maintenance
+=> Security
+=> Developing
+=> Help
+
+
+Note to players
+---------------
+webDiplomacy doesn't have an install wizard which checks and installs everything for you, the 
+code is made available mainly for developers who want to create unique webDiplomacy servers 
+(e.g. with unique translations or rule variants), or work on the official code.
+If your only experience of PHP and MySQL is installing phpBB, say, you may have trouble with 
+this software.
+
+If you just want to play with friends try to find an existing webDiplomacy server and set up 
+a private game there. (http://webdiplomacy.net/ is the official server.)
+
+
+requirements
+------------
+- PHP 5.2+
+- MySQL 5, with support for MyISAM, InnoDB, and memory tables
+- The GD 2 PHP extension, with FreeType support
+- Ability to send e-mail from the server (Access to an SMTP server or sendmail)
+- Quite a bit of disk space (depending on the expected size of the server; if 
+	your hosting space is measured in MB you may not have enough)
+- Quite a bit of processing power (if you've only got an account with an oversold 
+	shared-hosting company you may have problems; webDiplomacy probably uses more 
+	resources per user than, say, phpBB)
+- Ability to set up a crontab to fetch a web-page every 5 minutes or so, to run 
+	the game processing / server maintenance script
+
+
+Installing
+----------
+=> Database scripts
+Run install/install.sql to set up the initial data-set, you can run this in 
+phpMyAdmin's "Import" tab, if you don't have shell access.
+
+=> Config
+Edit config.sample.php to work with your setup, being very careful to read the warnings 
+about security issues. The salts/secrets, errorlog/orderlog directories, can all
+leave your server wide open if you don't set them right. Rename to config.php when ready.
+
+=> Log-on
+Once you've set config.php up you can use the random gameMasterSecret you entered
+to authenticate as the admin. First create a user via the registration page, then 
+once logged on go to gamemaster.php?gameMasterSecret=[yoursecret] .
+
+It will give you admin rights, then refresh the page as admin to run the gamemaster 
+script for the first time, which will initialize various stats and maintenance 
+processes. (This only works for the first user that does it, any other 
+admins/moderators have to be set via the admin control-panel.)
+
+Go to the Admin CP via the menu, find the "Toggle Maintenance Mode" action and 
+run it, preventing others from using the server up while you're testing it.
+
+=> Test
+Once that's set up you should go to Help->DATC. With Maintenance mode on it will 
+show a screen which can run through the DATC tests, which provides an easy way to 
+test that the installation was successful. Click Batch-test and it'll run through
+all the tests one by one. If maps are being generated successfully then everything
+is probably going to work. (Batch-testing the DATC tests may have problems in IE,
+try Firefox/Chrome/Safari until this is fixed.)
+
+=> Open up
+Once you've looked around, posted a test message etc, and double-checked your 
+config.php file for security issues, you can disable Maintenance mode via the 
+admin CP to allow regular users to access the installation.
+
+=> Start a processing cycle
+Now you need to set the system up so that games are automatically processed. This 
+means running gamemaster.php?gameMasterSecret=[yoursecret] every 5 minutes or so 
+from an automated script, via cron for example. Here is an example crontab:
+
+For example here is my cron line:
+*/5    *       *       *       *       /usr/bin/wget -O - 'http://webdiplomacy.net/gamemaster.php?gameMasterSecret=12345' >/dev/null 2>&1
+
+'*/5    *       *       *       *' sets the times the script should run (every 5 minutes)
+'/usr/bin/wget' is the program which downloads the script thus running it.
+'http://webdiplomacy.net/gamemaster.php?gameMasterSecret=12345' is the gamemaster URL
+'-O - ' specifies to output to standard output
+'>/dev/null 2>&1' specifies that the standard output should be discarded (i.e. just run the 
+page without saving the results)
+
+=> Check
+Once you're seeing the Last process time at the bottom of the page staying within 5 
+minutes of the current time the background processing is working, and everything should 
+be up and running. 
+
+
+Updating
+--------
+If updating from an older webDiplomacy version check the install/ folder subdirectories. Each 
+update should come with a readme. You may have to update through multiple versions.
+
+Remember to take backups! There aren't a large number of people testing these update scripts, 
+unlike phpBB updates or other scripts you may be familiar with, so bugs and tweaking are to be 
+expected as part of the updating process.
+
+
+Maintenance
+-----------
+Be sure to subscribe to the http://sf.net/projects/phpdiplomacy mailing list, to receive 
+emails when updates are released, as they'll probably contain bugfixes.
+
+There are a bunch of variables at the bottom that indicate the general health of the server, 
+whether the background-processor is running , whether there are any crashed games, etc. It's 
+best to keep an eye on these.
+
+=> Cleaning up
+The mapstore folder can be deleted every so often if it's getting too large, however if 
+space isn't a concern the directory structure is tree like and will scale to any reasonable 
+number of games, and cacheing maps saves lots of CPU-time.
+
+Access logs in the database also need to be cleaned periodically, the admin CP will wipe all 
+but the last 30 days of logs.
+
+If you have order-logging enabled the orderlog directory will fill up quickly, and can be 
+wiped regularly. If players aren't complaining that they entered different orders there's 
+no point logging orders to prove them wrong.
+
+If error logging is enabled logs can accumulate, but they should be handled and removed as they come.
+
+Game messages will probably take up the largest part of database storage. If keeping messages 
+from old games is less important than using little space they can be deleted for old games 
+occasionally (especially gamemaster auto-messages which also make a large part of the 
+GameMessages table)
+
+TerrStatusArchive and MovesArchive are the other two large tables; they contain data used to 
+draw old maps, and can be periodically wiped for old games if achived game history isn't 
+needed.
+
+Other than that check the admin CP status lists every so often which should highlight any problems 
+which are auto-detected.
+
+
+Security
+--------
+First off you must make sure you have read the warnings in the config comments very carefully. 
+The software won't try and detect silly mistakes that expose errorlogs/orderlogs to everyone. 
+If people can access errorlogs they may be able to see database passwords and other sensitive 
+info. If they can access the orderlogs they will know the moves others are entering.
+
+Security is taken seriously in the code; no security holes have yet been found in it, and 
+nowhere are there dynamic require_once statements or evals, or any of the common PHP security traps, 
+but this has to be supplemented by setting strict permissions and using secure passwords. 
+
+After installation everything can be and should be set to read-only except for the errorlog, 
+accesslog, and mapstore directories, which should be set so that nothing within them can be 
+executed (e.g. by using a .htaccess file for Apache).
+
+The admin, board, gamemaster, gamepanel, gamesearch, install, lib, locales, map, objects, and 
+register folders are all not required to be accessible from the web, and so access to these from
+the web server should be restricted (e.g. by using a .htaccess file for Apache).
+
+You may want to monitor webDiplomacy's resource use; it doesn't do this automatically and it
+may be using 
+
+
+Developing
+----------
+Check http://webdiplomacy.net/developers.php for the most up-to-date developer documentation.
+
+Be aware of the obligations of the AGPL software license we use: *If you change webDiplomacy you 
+must be prepared to share any changes you make. If that doesn't fit your requirements do not use 
+this software!* 
+
+
+Help
+----
+If you have any questions you can get help at the developer forum at http://forum.webdiplomacy.net/
+
+
+Kestas Kuliukas - 30/08/09