root/trunk/INSTALL

$Id$

================
1. PREREQUISITES
================

This is the prerequisites to install a collaborative platform with the PLACO generator.

* a PC 64bits with 1Go RAM, 2 IP addresses in your DNS : one for the administration,
    and one for the proxy. These addresses may be on the same Ethernet card,
    or on 2 separate cards
* at this time, a Linux DEBIAN 5 (Lenny) amd64 version installed (other distributions
  are planned for the future)
  (a Debian NetInstall ISO image can be found at :
    http://cdimage.debian.org/debian-cd/5.0.4/amd64/iso-cd/debian-504-amd64-netinst.iso)
* 1 network interfaces on this PC :
  * one (default is eth0) for the platform management : this interface must be plugged
    on the desired network
  * you may have one more interface (default is eth1) for the public interface :
    all the traffic of all the VM will then transit through it ; this interface
    also must be plugged on the desired network, but it has no need to have an IP
    address on this host
  See "5. NETWORK AND DNS REQUIREMENTS" below for more information.
  
* an Internet access to install on demand Linux DEBIAN from the mirror sites

If each of these items is validated, go to "2. INSTALLATION" below.

===============
2. INSTALLATION
===============

2 types of installation are possible :
  - as an end sysadmin : if you want to make an install onto a dedicated host
    for a production host. In this case, install_debian.sh downloads the lastest stable
    version, and the PLACO generator expands itself on the plain filesystem :
      /usr/bin, /usr/lib/placo, /var/placo, /etc/placo
    For this kind of install, goto 2.a
    
  - as a developper : if you want to contribute to the development of the tools.
    In this case, install_debian.sh downloads the lastest committed version on the trunk,
    and the PLACO generator is installed into the directory specified in the
    command line. This directory becomes also a subversion working-copy, so you
    will be able to commit your work into the central repository of the project.
    For this kind of install, goto 2.b

-----------------------------------------------------
2.a Install the platform generator as an end sysadmin
-----------------------------------------------------

* retrieve the lastest stable install script :

  # wget --no-check-certificate -P /tmp \
https://svn.math.cnrs.fr/placodev/tags/stable/install.sh

* run it :

  # chmod +x /tmp/install.sh
  # /tmp/install.sh

* reboot the host

* (optional) verify that Domain-0 is running :

  # xm list

* edit configuration file :

  # vi /etc/placo/default.defines

* before the creation of the platform, verify that eth1 is up, and check your configuration :

  # placocheck

* initialize the default platform :

  # placosh init_platform

  note : the output is logged in /var/log/placo/placosh.log.0

At this stage, you have a running minimal platform with a reverse proxy VM, a ldap VM
and a bdd VM. Now, go to "3. CHECKING"

--------------------------------------------------
2.b Install the platform generator as a developper
--------------------------------------------------

* If you are a developper of the PLACO project, retrieve the last committed install
  script :
  
  # wget --no-check-certificate -P /tmp \
           https://svn.math.cnrs.fr/placodev/trunk/install.sh

* run it :

  # chmod +x /tmp/install.sh
  # /tmp/install.sh -d wc_dir

  where wc_dir is the choosen local svn working-copy directory for the
  checkout (an absolute path is mandatory).
  With that, you will be able to write or modify some files, and to commit them in
  the PLACO subversion repository.
  
* reboot the host

* edit configuration file :

  # vi wc_dir/etc/default.defines

  and customize the value of the variables according to your network environment.

* before the creation of the platform, verify that eth0 or eth1 is up, and check
  your configuration :

  # wc_dir/bin/placocheck

* initialize the default platform :

  # wc_dir/bin/placosh init_platform

  note : the output is logged in /var/log/placo/placosh.log.0

At this stage, you have a running minimal platform with a reverse proxy VM, an ldap VM
and a bdd (database) VM. Now, go to "3. CHECKING"

===========
3. CHECKING
===========

* verify that the 3 VM proxy, ldap and bdd are running :
  # xm list

* verify that you can connect on them without any password, and then verify that the
  external network is reachable :

  # ssh proxy.default
  proxy:~# ping -c 3 placodev.mathrice.fr
  proxy:~# logout
  # ssh ldap.default
  ldap:~# ping  -c 3 placodev.mathrice.fr
  ldap:~# logout
  # ssh bdd.default
  bdd:~# ping  -c 3 placodev.mathrice.fr
  bdd:~# logout

If everything is allright, you are ready to play ! You can now add some new
VM on the platform.

===================================
4. ADD NEW SERVICES ON THE PLATFORM
===================================

At this time, you are the 3 mandatory VM in use : proxy, ldap and bdd.
To see what others VM provides the PLACO generator, type placosh (or
wc_dir/bin/placosh in devel mode) and at the prompt :

  placosh> ls install*

To add a new VM :
  - create a .defines file for that VM in ~/etc/default.defines (you can pick
    one from the ~/etc/default-dist directory)
  - run the corresponding install* script from the placo shell, for example :

      placosh> install_xxx

  note : the output is logged in /var/log/placo/placosh.log.0

At this time, the available VM are :
  * web_hosting: a APACHE server (providing virtual hosts, possibly
                 with CMS, and DAV access)
  * svn: a subversion server (providing versioning repositories)
  * list: a SYMPA server (providing mailling lists management)

--------------------------
4.a add the web hosting VM
--------------------------

To add the web_hosting VM :
  - create a web.defines file for that VM in ~/etc/default.defines, or copy
    (~/etc/default-dist/web.defines into ~/etc/default)
  - run the install_web_hosting script from the placo shell :

      # ~/bin/placosh
      placosh> install_web_hosting

  - then verify that the new VM is running :

      # xm list

--------------------------
4.b add the lists VM
--------------------------

To add the list VM :
  - create a lists.defines file for that VM in ~/etc/default.defines, or copy
    (~/etc/default-dist/lists.defines into ~/etc/default)
  - run the install_list script from the placo shell :

      # ~/bin/placosh
      placosh> install_list

  - then verify that the new VM is running :

      # xm list

--------------------------
4.c add the svn VM
--------------------------

To add the svn VM :
  - create a svn.defines file for that VM in ~/etc/default.defines, or copy
    (~/etc/default-dist/svn.defines into ~/etc/default)
  - run the install_svn script from the placo shell :

      # ~/bin/placosh
      placosh> install_svn

  - then verify that the new VM is running :

      # xm list

===============================
5. NETWORK AND DNS REQUIREMENTS
===============================
2 network interfaces are required on the PC :
  * one (default is eth0), for the platform management access
      This is a private access for the sysadmin team to the host. You must give to it
      an IP address. It is possible to use a local restricted network, but Internet must
      be reachable to install on-the-fly the platform
  * one (default is eth1), for the public access of the platform
      A virtual bridge is plugged on this interface. This interface must be up, but
      no IP address mut be associated on it, because the public IP address of the platform
      is owned by the proxy virtual machine (VM), which is also plugged on the same
      virtual bridge.
      The whole public traffic of all the VM transits by the proxy public interface.
      So this interface must be plugged on the right network (typically a public network)
      to provide a complete access to the platform customers.

A hand on a DNS server are also needed :
  * the canonical name of the platform must be inserted as an A record on the current
    domain name, and must be associated to the public IP address owned by the proxy
  * each alias needed by the HTTP virtual hosts must be defined on the DNS tables as
    a CNAME record of the canonical name

You can use placocheck command to verify tha each domain name defined in the defintion
file can be resolved or not.

=============
6. MONITORING
=============

To overview the status of the platform, go to with your web browser onto the
management IP of the host.