This file is a step-by-step how to for install and set up CodingTeam on your
own server. Before read this document, you should install all dependencies
listed in the README file.

 *****************************
   1. Apache HTTPD configuration
 *****************************

You have to set up a VirtualHost for CodingTeam like this example:

  NameVirtualHost *:80

  <VirtualHost *:80>
    ServerName example.org

    DocumentRoot "/path/to/codingteam"
    <Directory /path/to/codingteam>
      AllowOverride All
    </Directory>

    <Directory /path/to/codingteam/public>
      php_flag engine off
      AllowOverride None
      Options -Indexes
    </Directory>

    <Directory /path/to/codingteam/public/muclogs>
      Options +Indexes
    </Directory>

    ErrorLog /var/log/apache2/error.log
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined
    ServerSignature On
  </VirtualHost>

Now, you have to set up another VirtualHost for SVN repositories like this one:

  <VirtualHost *:80>
    ServerName svn.example.org
    include /path/to/codingteam/public/svn/_apache/*

    ErrorLog /var/log/apache2/error.log
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined
  </VirtualHost>

And now, another VirtualHost for HG repositories:

  <VirtualHost *:80>
    ServerName hg.example.org
    include /path/to/codingteam/public/hg/_apache/*

    RewriteEngine on
    RewriteRule (.*) /path/to/codingteam/scripts/hg/hgwebdir.cgi/$1

    DocumentRoot /path/to/codingteam/scripts/hg
    <Directory "/path/to/codingteam">
      AllowOverride None
    </Directory>

    <Directory "/path/to/codingteam/scripts/hg">
      Order allow,deny
      Allow from all
      AllowOverride All
      Options ExecCGI FollowSymLinks SymLinksIfOwnerMatch
      AddHandler cgi-script .cgi
    </Directory>

    ErrorLog /var/log/apache2/error.log
    LogLevel warn

    CustomLog /var/log/apache2/access.log combined
  </VirtualHost>

Also, please be sure that mod_rewrite and mod_cgi are activated. You should
check that other Apache HTTPD modules you load are compatible with them.

To get Mercurial repositories working, you should create a configuration file
in scripts/hg/hgweb.config:

  $ mv hgweb.config-example hgweb.config

 *****************************
   2. Folders owners and rights
 *****************************

First of all, directories inc/modules must be writable by CodingTeam (in order
to enable and disable modules and views). This is not mandatory but this is
required to configure the modules directly from CodingTeam.
Basically, you can do a:

  $ chown www-data:root inc/modules/*/infos.xml
  $ chown www-data:root inc/data/*

Now, you have to create some directories in the public/ one.

The firsts have to be writable by PHP, so, you must do a chmod 770 and set the
owner www-data:root:

  public/cache
    → public/cache/atom
    → public/cache/rss
    → public/cache/xhtml

  public/upload
    → public/upload/avatars
    → public/upload/briefcase
    → public/upload/projects

For DVCS/VCS integration, you must create following directories. This allows
CodingTeam to create DVCS/VCS repositories in the public/ paths. Apache
configurations are stored in public/*/_apache and authentification files in
public/*/_authz.
Just recursively set the owner www-data:root on these directory.

  public/svn
    → public/svn/_apache
    → public/svn/_authz

  public/hg
    → public/hg/_apache
    → public/hg/_authz

If you want, you can create a folder for the logs of all Jabber rooms. This
folder must be readable by Apache, but not writable.

  public/muclogs

 *****************************
   3. CodingTeam configuration
 *****************************

CodingTeam use a XML-based configuration. There is an example in
inc/codingteam.cfg-example. Start by rename it:

  $ mv codingteam.cfg-example codingteam.cfg

Now, you can start to write your config (your XML-base file have to be conform
to the XSD XMLSchema).

Here a little explanations of the possibles values:

  db->type:                The software that run the database
                           There are 2 database software supported:
                               * for MySQL 5.x:           `mysql`
                               * for PostgreSQL:          `pgsql`  EXPERIMENTAL
  db->hostname:            The hostname of your mysql base
  db->database:            The name of the database 
  db->username:            The name of the user
  db->password:            The password of the user

  svn->subdomain:          Subdomain for SVNs (second VirtualHost example)
  svn->location:           Text between subdomain and project name (default: /)

  hg->subdomain:           Subdomain for HGs (third VirtualHost example)
  hg->location:            Text between subdomain and project name (default: /)

  auth->method:            The method used by users to login
                           There are 2 methods supported:
                               * by username/password:    `sql`
                               * by XMPP (XEP-0070):      `xmpp`   EXPERIMENTAL

  errors->show_debug:      1 to show source code and memory dump on a error
  errors->catch_fatal:     1 to catch even PHP fatal errors
  errors->show_notice:     1 to show PHP E_NOTICE errors
  errors->log_errors:      1 to log all errors in a file
  errors->log_level:       -1, 0, 1, 2 or 3

  config->theme:           The template theme for your forge.
                           There are 2 templates distributed with CodingTeam:
                               * The default template:    `default`
                               * Dark simple template:    `simple`

Remarks:
 - You really should disable errors->show_debug in a production environement
   because some data in the dump can be very critical and a bad intent person
   can use them.
 - If you disable errors->catch_fatal boolean, don't forget to comment the
   line 30 of the root .htaccess ("php_flag display_errors Off") or fatal
   errors will not be displayed when they will occur (just a white screen).
 - If you enable errors->show_notice boolean, notice errors will be displayed
   like every other errors (blocking and causing die), this is not recommanded
   in a production environement but is useful to debug. If you disable it,
   E_NOTICE errors can still be logged.
 - If you enable errors->log_errors boolean you should create an error.log
   file in the CodingTeam root directory and set www-data:root as owner of
   this file.
 - When you enable errors->log_errors, you should set an appropriate value for
   errors->log_level. It's an integer of the first error level to catch. So, if
   you want to log only critical (2) and internal errors (3), set it to 2. The
   recommanded value is 1, it catches important, critical and internal errors.

Now, you are ready to import the SQL shema in your database with the
codingteam.sql file!

When the SQL shema is imported, you should follow this final step to add a
minimal configuration for CodingTeam:

  INSERT INTO `config` (`group`, `field`, `value`, `text`) VALUES
  ('global', 'mailfrom', 'MyForgeName <mail@domain.net>', 'The FROM and REPLYTO headers of sended mail.'),
  ('global', 'cache-max-files', '2000', 'The maximum files number for the cache.'),
  ('global', 'slogan', 'Create. Participate. Evolve. Free Software.', 'The slogan of your forge.'),
  ('global', 'show-exectime', 'false', 'true or false if you want to hide execution time.'),
  ('global', 'show-informationbox', 'true', 'true or false if you want to hide the search bar.'),
  ('global', 'force-login', 'false', 'true or false if you want to make your forge public.'),
  ('global', 'briefcase-max', '20', 'The maximum size (in Mo) allowed for each user\'s briefcase.'),
  ('global', 'authorize-anonymous-posts', 'true', 'Authorize content posted by anonymous.'),

  ('jabber', 'omnipresence-jid', 'presence.jabberfr.org', 'The Jabber ID of the Omnipresence bot.'),
  ('jabber', 'omnipresence-url', 'http://presence.jabberfr.org/', 'The HTTP URL of the Omnipresence bot.'),
  ('jabber', 'server', 'domain.net', 'The domain of the jabber server.'),
  ('jabber', 'muc', 'conference.domain.net', 'The Jabber ID of the conference component.'),
  ('jabber', 'username', 'username', 'The username of the bot.'),
  ('jabber', 'password', 'password', 'The password of the bot.'),
  ('jabber', 'nickname', 'nickname', 'The nickname of the bot.'),
  ('jabber', 'allow-notifications', 'false', 'true or false if you don\t want to allow notifications over XMPP.'),

  ('openforge', 'esearch-active', 'false', 'true or false if you want to disable external search.'),
  ('openforge', 'esearch-servers', '', 'A list of external servers, separated by a ";".'),

  ('projects', 'need-validate', 'true', 'true or false if you don\'t want to validate all new projects.'),
  ('projects', 'allow-adding', 'true', 'true or false if you don\'t want to disable projects adding.'),
  ('projects', 'allow-donation', 'false', 'true or false if you don\'t want to disable projects donation.'),
  ('projects', 'allow-private', 'false', 'true or false if you don\'t want private projects.'),

  ('users', 'allow-registration', 'true', 'true or false if you don\'t want to disable users registration.');

By default, omnipresence-jid and omnipresence-url are already sets because
it's the only Omnipresence server we know. Omnipresence allows CodingTeam to
retrieve the avatar of a member via his Jabber account and some great features
like that. You could install your own Omnipresence and use it instead of the
JabberFR ones. See: http://codingteam.net/project/omnipresence

Now, you have to configure MUCKl (the web-based client for Jabber chatrooms).
There are 2 files to edit in inc/libs/muckl, start by rename them:

  $ mv config.js-example config.js && mv .htaccess-example .htaccess

In config.js, you should set XMPPDOMAIN and MUCSERVER (at lines 51-52).
XMPPDOMAIN is the equivalent of `jabber.server` and MUCSERVER of `jabber.muc`
(see above).

In .htaccess, you should edit the URL to your Jabber server at line 7.
Note that HTTP polling/binding needs some configuration on the server-side.

Additionaly, you need to enable 3 Apache modules:
 - proxy
 - proxy_connect
 - proxy_http

You can now start Apache and discover your new forge. :)

 *****************************
   4. Internationalization
 *****************************

If you want to build translation files, you just have to go in scripts/i18n and
launch:

  ./create_mo

It will prompt you the language you want to construct (only french is available
at the moment) and it will create the codingteam.mo file for this language.
That's all you need to do to translate your forge.

 *****************************
   5. CodingTeam maintenance
 *****************************

At this step, CodingTeam is ready to work on your server. You just have to
configure a few recurring tasks.

1) XMPP notifications.

If you want your users to use XMPP notifications, you have to set the key
jabber.allow-notifications to TRUE in the configuration keys editor.

You also have to add a cron rule:

  */5 * * * * /path/to/codingteam/scripts/miscellaneous/xmpp-notifications.php

2) Apache HTTP reload for SCM.

You need to reload the configuration of the HTTPD server each time you add a
DVCS/VCS repository. That's why scripts/miscellaneous/ contains the
apache-reload.sh Shell script.

There are two methods to use this script, with cron and incron. The second way,
by using incron, is *highly* recommended.

You can add a similar rule to your crontab:

  0 0 * * * /path/to/codingteam/scripts/miscellaneous/apache-reload.sh

But this has a security issue. While the server hasn't be reloaded, the new
configuration file created with the new repository isn't read and thus
everyone have write access on them.

The solution is to use incron (packaged in a lot of GNU/Linux distributions).
<http://inotify.aiken.cz/?section=incron&page=about&lang=en>

Here are the rules that you can write in your incrontab:

  /path/to/codingteam/public/svn/_apache IN_CLOSE_WRITE /path/to/codingteam/scripts/miscellaneous/apache-reload.sh
  /path/to/codingteam/public/hg/_apache IN_CLOSE_WRITE /path/to/codingteam/scripts/miscellaneous/apache-reload.sh

 *****************************
   6. Drink a beer!
 *****************************

Ok, you finished!
Once you did everything that comes before, CodingTeam should work fine.