Publite

Publite is a leaner and meaner version of the old Pubserver scripts that runs on http://www.freeciv.org/. They should enable anyone with a Unix-shell to run a permanent server of their own with support for custom settings, multiple checkouts, savegames and rulesets.
= INSTALLATION =
Installation on a Unix-shell should be easy for someone somewhat experienced with such shells. Here is a concise list of what you need to do:
* Create a new user, say 'freeciv' or 'pubserver'.
* Untar the publite tarball in the home directory of this new user.
* Create a data directory, and ensure that it is owned by the new user created above.
* Edit config.sh to set the correct paths and configuration options. Default suggested root path is /var/freeciv
* Run ./update_servers.sh once by hand.
* Create your servers in the designated server directory (designated in config.sh). Each file in this directory will spawn one server with the given options.
* Create your builds in the designated builds directory (designated in config.sh). Each file in this directory will be updated and built into binaries for use with the servers above whenever the update_servers.sh script is run.
* Update whatever .serv files you want to use (set in server configuration file above).
* Start servers. If this works, add the update servers script to cron (24 hours, eg) and the starts servers script to your boot scripts.
= CONFIGURATION =
You need to change these files:
* config.sh contains all overall publite system configuration options.
* There must be at least one file detailing the configuration of a server (usually in /servers).
* There must be at least one file describing a cvs checkout to build into a binary (usually in /builds).
* There must be at least one server settings file (usually /var/freeciv/options/standard.serv)
== BUILD CONFIGURATION ==
A build configuration file resides inside $BUILDCONFIGDIR. Each file contains instructions to fetch, configure, and compile a game server.
The build configuration file must contain these variables:
BUILD_NAME="<build name>-`date +%F`"
PATCHES="<patch names or just set this to nothing>"
FETCH_METHOD="copy"
AUTOGEN_OPTS=""
and should contain some of the following variables depending on $FETCH_METHOD:
COPY_DIR="<path to local source tree>-`date +%F`"
SVN_URL="svn://svn.gna.org/svn/freeciv/trunk"
SVN_OPTS="--revision {`date +%F`}"
;BUILD_NAME
: The base name of this build's source directory. In the example above: "-`date +%F`" is merely an example.
;PATCHES
: Patches that we will apply to this build's source tree these need to be complete filenames separated by spaces or directory names (which house patches). These need to exist in $PATCHDIR
;FETCH_METHOD
: The method to procure the freeciv sources: can be "svn" for subvserion checkout or "copy" to copy from a local tree. N.B.: "svn" has not been tested.
;AUTOGEN_OPTS
: Extra autogen.sh parameters for just this particular build. Use $GLOBAL_AUTOGEN_OPTS in config.sh for options on all builds
;COPY_DIR
: Use this if $FETCH_METHOD = "copy". This is the path to the tree to be copied over.
;SVN_URL, SVN_OPTS
: Use these if $FETCH_METHOD = "svn". Gives the parameters and URL to the svn command.
== SERVER CONFIGURATION ==
A server configuration file resides in $SERVERCONFIGDIR.
The server configuration file should contain these lines:
SERVER_BUILD="<build name>"
SERVER_CMD="<some extra command line options>"
SERVER_PORT="5555"
SERVER_RC="xxxxx.serv"
QUIT_ON_NEXT_READ="no"
;SERVER_BUILD
: The name of the build (that produces the binary) that this server instance will use (see Build Configuration)
; SERVER_CMD
: Extra commandline switches or options. things that should not go here: -p -P -q -m -S -e --saves --read as they are already included via run_server.sh
;SERVER_PORT
: A single port number where this server will run. If you want a server instance to run on multiple ports, then try using utility/clone_server_ports.sh
;SERVER_RC
: the .serv file (in $RCDIR) which will be read by the server on startup
;QUIT_ON_NEXT_READ
: A variable which can be set dynamically if you want the server to gracefully after it's done running... (it will normally restart on the same port) Set to "yes" if you want it to quit. also see utility/[un]quit_servers.sh
== SERVER SETTINGS ==
The server settings file is a normal ".serv" configuration file, and contains a list of server commands that will be executed when the server starts. It is recommended that 'metapatches', 'metatopic' and 'metamessage' are set here, at least. These files must reside in $RCDIR.
== VARIABLES ==
These variables are defined in config.sh.
;PUBHOME
: Root directory of pubserver. config.sh must be in this directory. main scripts (update_servers, run_servers, etc) also.
;LOGDIR
: Directory where logfiles are kept.
;SERVERCONFIGDIR
: Directory where server instance config files are stored. Each file represents a server started on a particular port.
;BUILDCONFIGDIR
: Directory where build instance config files are stored. Each file represents a build process for a single server binary (patches, compile-tile options, etc).
;SRCDIR
: Directory where source code resides used to build game server binaries. May have multiple codebases depending on the build instructions of the files in BUILDCONFIGDIR.
;TMPDIR
: Directory for temporary files. Used primarily for temporary log files.
;GAMESDIR
: Directory where complete games are saved. Subdirectories of this will be game identification numbers.
;PATCHDIR
: Directory where the build configuration finds patches to apply to source code.
;RCDIR
: Directory where .serv files can be found that are used by the server config files.
;EXECDIR
: Directory where helper scripts can be found.
;ARCHIVEDIR
: Directory where post-game statistics, maps, charts are stored. Subdirectories of this will be game identification numbers.
;INSTDIR
: Directory (non-absolute!) where the build will install the binary and rulesets. This directory is copied to $GAMESDIR/game_id by run_server.sh
;UPDATE_LOG
: Log file for update actions (used in update_servers.sh)
;RUN_LOG
: Log file for run actions (used in start_servers.sh, run_server.sh, post_process.sh)
;RANKING_LOG
: Log file for ranking. (used in $EXECDIR/ranking.pl)
= RUNNING =
The script start_servers.sh should be run on server boot, and will fork processes that will keep servers up and running until they crash. Crashed servers need to be relaunched manually for now, by rerunning this script. Still running servers will not be duplicated but errors will be logged since duplication is attempted but fails due to port binding failure. This is ugly and should be improved.
The script update_servers.sh updates the cvs checkout which creates the binary, and builds another binary. It should be put in a cron script, and run with nice if possible to avoid impacting on running servers.
Category:Pubserver