Installation instructions


Installation instructions
-------------------------

Help with installation:

   If you need assistance or have questions about the install procedure,
   please ask in the Support-forum of the LIVE-server:

      http://www.dragongoserver.net/forum/list.php?forum=2

   For developers there's also a normally hidden development-forum on the
   LIVE-server. If you want to have access, please file a request in the
   Support-forum on the LIVE-server.


Server Requirements:

*) A webserver which can use php, e.g., apache (http://httpd.apache.org)
*) PHP >= 5.2.0 (http://www.php.net)
*) MySQL >= 5.0.38 (http://www.mysql.com)
*) GD >= 2.0.0 to draw rating graph and upload images (http://www.boutell.com/gd/)

Optionally

*) git client (http://git-scm.com)
*) FreeType for optional fonts in rating graph (http://www.freetype.org)

Last versions used by Dragon Live Server:
   Apache Version Apache/2.2.3 (Unix) PHP/5.1.6
   MySQL 5.0.45

Optional but recommended:
   APC 3.1.9  shared-memory cache

Client Requirements:
*) browser supporting at least JavaScript 1.8.1 is required for features relying on jQuery


#--------------------------------------------------------------------

1) Download sources with images:

Dragon root-directory referred to as DGS_ROOT.

Either download from Git-repository on SourceForge.net:

   # with an existing SourceForge-account 'USER':
   # (to ease updates it's a good idea to upload your public SSH-key on SourceForge
   #  to avoid repeated authentification)
   git clone ssh://USER@git.code.sf.net/p/dragongoserver/dgs-main DGS_ROOT

   # OR: with an anonymous read-only checkout from SourceForge:
   git clone git://git.code.sf.net/p/dragongoserver/dgs-main DGS_ROOT

   # OR: download a snapshot from   http://www.dragongoserver.net/snapshot.php

For both git clone methods, the images are already included, while the download
of an archive from the snapshot-page does only contain the sources while the images
must be downloaded separately from the snapshot-page as well.

If the images are downloaded from the snapshot, unpack the archive into the dragon-root
directory to obtain a tree like:


      DGS_ROOT/
         include/
         forum/
         ...
         images/
            flags/
         5/
         7/
         ...
         50/

Copy or link  /images/favicon.ico  into the DGS_ROOT folder (or place your own favicon.ico
in the root folder). Some older browsers ignore the shortcut-icon directive
and expects it to be in the document-root.

Copy all  /images/apple-touch-icon-*.png  into the DGS_ROOT folder to avoid 'page_not_found'-errors.
For reference see also http://mathiasbynens.be/notes/touch-icons


#--------------------------------------------------------------------

2) Make a mysql database and a mysql user to access the database:

IMPORTANT NOTE:
For creating and altering database tables you will need a separate database admin user 'dragon-admin'.
For safety reasons, the db-user used for the website MUST NOT have rights to create, alter or drop tables!

   mysql> CREATE DATABASE dragondb;
   mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE TEMPORARY TABLES, LOCK TABLES
          ON dragondb.* TO dragonuser@localhost IDENTIFIED BY 'secret';

As dragon-admin user you may either use the database 'root'-user which has all rights or
create a separate user with additional access rights.

   mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE TEMPORARY TABLES, LOCK TABLES,
          CREATE, ALTER, DROP ON dragondb.* TO dragonadmin@localhost IDENTIFIED BY 'adminsecret';


#--------------------------------------------------------------------

3) Create mysql tables:

Create database-tables needed for a Dragon Go Server
NOTE: This DDL-Export has been created using PHPMyAdmin: Export(DB) with Export (SQL) and Options:
      - Add 'IF NOT EXISTS': on
      - Add 'AUTO_INCREMENT' value: off
      - Enclose table and field names with backquotes: on
      - Data: off
      'dragon-ddl.sql' (unused tables removed)

With an db admin user create all the tables:

   > mysql -D dragondb < specs/db/dragon-ddl.sql

   ## or maybe, if needed by your configuration, the more complete:
   > mysql -D dragondb -h mysqlhost -u dragon-admin -p < specs/db/dragon-ddl.sql


Import mandatory initial-data for the server:

   > mysql -D dragondb < specs/db/dragon-data.sql


IMPORTANT NOTE:
   Before you try logging in on your local DGS-server, ensure that the translations are added first.
   Otherwise the import may fail because of changed primary-keys of translation-data that will be
   inserted by the running server itself.

Create the translations:

  > mkdir translations
  > su -c 'chgrp www-data translations'
  > chmod 775 translations/
  > pushd scripts
  > php make_all_translationfiles.php
  > popd


Now, add the latest translations.
The data file can be downloaded and extracted from:

   http://www.dragongoserver.net/snapshot.php

   gunzip Translationdata.mysql.gz
   mysql -D dragondb < Translationdata.mysql


(( The following creation of an DGS admin user could be delayed until you need it:
Add at least one super-admin user by registering a user via the website and
then give him the full set of priviledges by manually setting his
Adminlevel field to 0xffff (setting all bits) in the Players table.

You need a working mailing setup for this, because a user-registration sends out a mail
with a validation-code to activate the new account. For the registered admin-user
you either temporarily set 'SEND_ACTIVATION_MAIL' to false in your 'include/config-local.php',
which bypasses the mail-activation, or you manually do the activation with the
"ACTIVATE"-statements shown below (2nd next paragraph):

   > mysql -D dragondb

   mysql> UPDATE Players SET Adminlevel=0xffff WHERE Handle='adminusernick';

Then, this user will be able to manage the other admins in the Admin-menu.

You may also need to manually activate the super-admins registration,
because sending email may not work yet sending out a verification-code
after the registration.

   # ACTIVATE-statements:
   mysql> UPDATE Players SET UserFlags=UserFlags & (4|8) WHERE Handle='adminusernick';
   mysql> UPDATE Verification AS V INNER JOIN Players AS P ON P.ID=V.uid
             SET V.Verified=NOW(), V.Counter=V.Counter+1 WHERE P.Handle='adminusernick';

))




#--------------------------------------------------------------------

4) Adjust config of software and adjust file permissions:

NOTE: order of the following items is not strict. You may need to re-edit the
      local-config multiple times for some of the items.


* Copy config-template and adjust for local configuration:

  > cp include/config.php include/config-local.php

  Adjust 'include/config-local.php' to fit to your environment and needed set of
  DGS-features. For configuration of the cache read on first.

  DGS allows a file-based or APC-based caching. For usage and configuration of
  the caching you need to read some chapters of 'specs/caching.txt':

      - chapter (2a) to install the APC-cache, including the 'apc-live.php'-script

      - chapter (2) in full if you also want to use file-based caching

      - chapter (3) to adjust the cache-configuration in your local config

      - chapter (4) to get familiar with cache-admin scripts

* Edit permissions for include/config-local.php:

  Find out which group your webserver is using (e.g. www-data).
  > su -c 'chgrp www-data include/config-local.php'
  > chmod 640 include/config-local.php

* If wanted, create a CACHE_FOLDER (from include/config-local.php) with
  the proper user/groups and rights, so that your web-server
  can read and write that directory.

  # Create the CACHE_FOLDER-directory (example):
  mkdir temp
  chmod 775 temp
  su -c 'chgrp www-data temp'

* Create a directory to store user-pictures with write-access for the webserver.
  You can create a sub-directory in the document-root or use an alias /userpic
  pointing to a folder to store images. Adjust USERPIC_FOLDER in the local
  config-file.

  NOTE: Be aware, that this is a security risk, if scripts are uploaded into
        folder. The code assure, that only images are uploaded though.
        Still some image-formats could be "infected". This case should be
        handled by DGS-admins.

  Userpic-directory should be at a place that is archived within a regular backup,
  because the pictures are not stored in the database.

  # Example using CACHE_FOLDER from above as storage:
  # (assert that URL-part '/userpic' points to USERPIC_FOLDER-directory
  mkdir temp/userpic
  ln -s temp/userpic .
  su -c 'chgrp www-data temp/userpic'
  su -c 'chmod g+ws temp/userpic'

* Create a directory outside of the document-root with write-access for the webserver.
  This must be configured in "include/config-local.php" with DATASTORE_FOLDER.
  The directory can contains sensitive data, that should not be available via web-access.
  Therefore it should either be located outside of the document-root, or otherwise
  if located in a sub-directory in the document-root at least put a web-password on
  it as required for the scripts-sub-dir.

  If the folder is not existing and the web-user has the required rights,
  the folder will be created by the webserver on-the-fly. But for that, the webserver
  user must have the necessary rights in the parent directory.

  # Create the DATASTORE_FOLDER-directory (example) and sub-dirs for RSS/quick-status/WAP:
  mkdir data-store
  mkdir data-store/rss data-store/qst data-store/wap
  chmod -R 775 data-store
  su -c 'chgrp -R www-data data-store'

* Eventually you need to adjust the used timezone.
  This can be done by creating a file in the dragon-root:

     filename:              timeadjust.php
     content (for example): <?php $timeadjust = ...; ?>

  This file is read by the PHP-include 'include/quick_common.php'
  and the unit for the variable $timeadjust is seconds.
  It's added to form the "current timestamp" ($NOW).

* Now you need to create the remaining page-specific translations.
  After ensuring, that all the previous steps to prepare translations have been taken
  as described above, read and execute the directives in 'scripts/README.translations'.

* If you want to adjust the source-code, please have a look to the
  notes in 'scripts/README.developers'

* MySQL Database Config:

  In order to support the forum search using a good full-text index,
  the real DragonGoServer http://www.dragongoserver.net/ changed the
  following server variable:

     http://dev.mysql.com/doc/refman/5.0/en/server-system-variables.html#sysvar_ft_min_word_len

     ft_min_word_len  =  1     (default-value is 4)

  After the change you have to rebuild the index for the following tables with:

     REPAIR TABLE Messages QUICK
     REPAIR TABLE Posts QUICK

* PHP config:

  IMPORTANT NOTE: safe_mode should be OFF!

  By now, Dragon works with these PHP directives:

     allow_call_time_pass_reference = Off ;Unused
     allow_url_fopen = Off ;Unused
     always_populate_raw_post_data = Off ;Unused
     arg_separator.input = &
     arg_separator.output = "&amp;" ;or = "&"
     asp_tags = Off ;Unused
     default_charset = ;set to empty or commented
     default_mimetype = "text/html"
     error_reporting = E_ALL
     file_uploads = On ;else the pattern upload will be disabled
     gpc_order = GPC
     implicit_flush = Off ;Unused
     magic_quotes_gpc = Off ;Don't care
     magic_quotes_runtime = Off
     magic_quotes_sybase = Off
     max_execution_time = 30 ;except for some rebuilding scripts with large databases
     memory_limit = 24M
     output_buffering = Off
     post_max_size = 8M ;greater than upload_max_filesize if used
     precision = 14
     register_argc_argv = Off ;Unused
     register_globals = Off ;Don't care
     safe_mode = Off ;else safe_mode_allowed_env_vars= must allow putenv() to modify 'TZ'
    ;set sendmail_* options to your needs
     short_open_tag = Off ;Unused
     track_vars = On ;always enabled as of PHP 4.0.3
     upload_max_filesize = 2M ;if used
     variables_order = EGPCS ;or empty
    [MySQL]
     mysql.allow_persistent = Off ;Unused
     mysql.default_host = ;Unused
     mysql.default_user = ;Unused
     mysql.default_password = ;Unused
     mysql.max_links = -1 ;Unused
     mysql.trace_mode = Off  ; needed for FOUND_ROWS() to work, see config.php ALLOW_SQL_CALC_ROWS

* if using XDebug (or similar) for local PHP development:

  The max-nesting-level of xdebug must be raised, otherwise encoding JSON for the game-editor will fail
  (happens if ENABLE_GAME_VIEWER=true and game-page is used):

  Edit xdebug-config for PHP running in Apache, probably at "/etc/php5/apache2/conf.d/xdebug.ini" and
  adjust (or add) the following config-line:

     xdebug.max_nesting_level=1500


* OPTIONAL: for using FreeType-font drawing rating graphs:

Check and adjust defines in 'include/graph.php':
- TTF_PATH
- TTF_NAME
- TTF_HEIGHT




#--------------------------------------------------------------------

5) Add some cron jobs. These should preferrably be run on a remote machine, so that the
   clock is not running when the network is down.

   Adjust MAILTO in crontab accordingly.

   NOTE: (( Windows NT/200x/XP - some freeware clones of cron may be found on the web ))

   NOTE: For debugging purposes you can use "wget -v" instead of "wget -q" to get a verbose
         output to STDOUT mailed to you.

> crontab -e

----------------
# min  hour day  mon  weekday
# 0-59 0-23 0-31 0-12 0-7

# DGS-live-server triggering clocks
MAILTO= < EMAIL-OF-YOUR-CHOICE >

*/5  *  *  *  *   wget -q -O - http://www.dragongoserver.net/clock_tick.php
0,30 *  *  *  *   wget -q --read-timeout=1800 -O - http://www.dragongoserver.net/halfhourly_cron.php
58   *  *  *  *   wget -q -O - http://www.dragongoserver.net/hourly_cron.php
25   5  *  *  *   wget -q -O - http://www.dragongoserver.net/daily_cron.php
#7,22,37,52 * * * *   wget -q -O - http://www.dragongoserver.net/tournaments/cron_tournaments.php
----------------




#--------------------------------------------------------------------

6) Protect the scripts/ folder from outside access:
   The scripts/ folder contains sensible tools reserved to the developers
   or the admins team.
   You have to protect it with an authentification process (using, for
   example, the .htaccess AuthUserFile command) or at least move the
   whole folder outside the server root tree when you have used it.




#--------------------------------------------------------------------

7) If you have problems you can ask for help in the Support or Development forum
   at dragon   http://www.dragongoserver.net   as explained in the "help" note
   at the top of this documentation.

   If you are successful and have a running Dragon server,
   we would appreciate a note in the dragon forums as well.

Hosted by  Samuraj Logo