These instructions show how to install:

1. mod_mirrorbrain, the Apache module
2. other needed components
3. the database

It requires a backend to work with, which can be found at
https://forgesvn1.novell.com/svn/opensuse/trunk/tools/download-redirector-v2

RPM packages are here:
http://download.opensuse.org/repositories/Apache:/Modules/
http://club.mandriva.com/xwiki/bin/view/rpms/Application/apache-mod_zrkadlo

It can be built with the following steps:
# unpack the tarball
cd mod_mirrorbrain
apxs2 -c mod_mirrorbrain.c

To install the module in the right place, you would typically call
apxs2 -i mod_mirrorbrain.c

Building, installing and activation can typically be combined in one call:
apxs2 -cia mod_mirrorbrain.c



After installation of mod_mirrorbrain, you'll need to:


- install GeoIP library, commandline tools, and geoip apache module
  (openSUSE/SLE packages: GeoIP, libGeoIP1, apache2-mod_geoip)

- configure mod_geoip:
    GeoIPEnable On
    GeoIPOutput Env
    GeoIPDBFile /usr/share/GeoIP/GeoIP.dat MMapCache
  (You would typically put this into the server-wide context of a virtual host.)

  Note that a caching mode like MMapCache needs to be used, when Apache runs with the worker MPM.
  http://forum.maxmind.com/viewtopic.php?p=2078

- install mod_form
  http://apache.webthing.com/svn/apache/forms/mod_form.c
  http://apache.webthing.com/svn/apache/forms/mod_form.h
  (openSUSE/SLE package: apache2-webthings-collection)

- install the following Python modules:
      python-cmdln
      python-sqlobject
      python-mysql (when using MySQL)
      python-psycopg2 (when using PostgreSQL)

- for the scanner, which is written in Perl, a few Perl modules are required:
      perl-libwww-perl
      perl-DBD-mysql (when using MySQL)
      perl-DBD-Pg (when using PostgreSQL)


- choose a database to use with MirrorBrain, and continue with the respective
  description below:


   a) Using MySQL

      - install the MySQL database adapter for the DBD library
        (openSUSE/SLE package: libapr-util1-dbd-mysql)

      
      - install and start MySQL
      
      - log into your database at root:
          mysql -u root -p
        there, create the database and grant write permissions for a local user:
          create database mirrorbrain;
          grant all privileges on mirrorbrain.* to wwwrun@localhost identified by '12345';
      
        run the sql file which creates the tables and indices:
          mysql -u wwwrun -p -D mirrorbrain < /usr/share/doc/packages/apache2-mod_zrkadlo/sql/mirrorbrain-mysql.sql
      
      - the mysql InnoDB engine needs to be configured to use enough memory for the
        database. This is probably the most important thing to know and the most
        frequent deployment error, to not tune this. Use the innodb_buffer_pool_size
        value to match it to the size of your database. The default value is tiny.
        Although, when your database is tiny, too, it won't matter much. But for
        larger databases, the value needs to be increased, possibly considerably.
  

    b) Using PostgreSQL

       - install the PostgreSQL database adapter for the DBD library
         (openSUSE/SLE package: libapr-util1-dbd-pgsql)
       
       - install postgresql and start it

       - create the postgresql user account and database:


           su - postgres
           
           root@powerpc:~ # su - postgres
           postgres@powerpc:~> createuser -P mb
           Enter password for new role: 
           Enter it again: 
           Shall the new role be a superuser? (y/n) n
           Shall the new role be allowed to create databases? (y/n) n
           Shall the new role be allowed to create more new roles? (y/n) n
           CREATE ROLE
           
           postgres@powerpc:~> createdb -O mb mirrorbrain
           CREATE DATABASE
           postgres@powerpc:~> 


           postgres@powerpc:~> vi data/pg_hba.conf
           # TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
           # "local" is for Unix domain socket connections only
           #local   all         all                               ident sameuser
           #local   all         all                               trust
           local   all         all                               password
           # IPv4 local connections:
           host    all         all         127.0.0.1/32          password
           # IPv6 local connections:
           host    all         all         ::1/128               password
           
           
           root@powerpc:~ # rcpostgresql restart
           
           root@powerpc:~ # su - postgres
           postgres@powerpc:~> psql mirrorbrain mb
           Password for user mb: 
           Welcome to psql 8.1.11, the PostgreSQL interactive terminal.
           [...]




       - psql -U mb -f /dev/shm/mirrorbrain-postgresql.sql mirrorbrain

           Password for user mb: 
           BEGIN
           psql:/dev/shm/mirrorbrain-postgresql.sql:14: NOTICE:  CREATE TABLE will create implicit sequence "file_id_seq" for serial column "file.id"
           psql:/dev/shm/mirrorbrain-postgresql.sql:14: NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "file_pkey" for table "file"
           CREATE TABLE
           CREATE INDEX
           psql:/dev/shm/mirrorbrain-postgresql.sql:45: NOTICE:  CREATE TABLE will create implicit sequence "server_id_seq" for serial column "server.id"
           psql:/dev/shm/mirrorbrain-postgresql.sql:45: NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "server_pkey" for table "server"
           psql:/dev/shm/mirrorbrain-postgresql.sql:45: NOTICE:  CREATE TABLE / UNIQUE will create implicit index "server_identifier_key" for table "server"
           CREATE TABLE
           CREATE INDEX
           psql:/dev/shm/mirrorbrain-postgresql.sql:61: NOTICE:  CREATE TABLE / UNIQUE will create implicit index "file_server_fileid_key" for table "file_server"
           CREATE TABLE
           CREATE INDEX
           CREATE INDEX
           psql:/dev/shm/mirrorbrain-postgresql.sql:83: NOTICE:  CREATE TABLE will create implicit sequence "marker_id_seq" for serial column "marker.id"
           psql:/dev/shm/mirrorbrain-postgresql.sql:83: NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "marker_pkey" for table "marker"
           CREATE TABLE
           psql:/dev/shm/mirrorbrain-postgresql.sql:92: NOTICE:  CREATE TABLE will create implicit sequence "country_id_seq" for serial column "country.id"
           psql:/dev/shm/mirrorbrain-postgresql.sql:92: NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index "country_pkey" for table "country"
           CREATE TABLE
           CREATE FUNCTION
           COMMIT




- create a group and user to run the mirrorbrain tools under:
    groupadd mirrorbrain
    useradd mirrorbrain -g mirrorbrain

- create /etc/mirrorbrain.conf with the content below. File permissions should
  be 0640, ownership root:mirrorbrain


  [general]
  instances = go-oo

  [go-oo]
  dbuser = wwwrun
  dbpass = 12345
  # use "mysql" for MySQL, and "postgresql" for PostgreSQL
  dbdriver = mysql
  dbhost = your_host.example.com
  dbport = 3306
  dbname = mirrorbrain
  
  [mirrorprobe]
  logfile = /var/log/mirrorprobe.log
  loglevel = INFO
  mailto = your_mail@example.com, another_mail@example.com


- collect a list of mirrors (their HTTP baseurl, and their rsync or FTP baseurl
  for scanning). For example:

    http://ftp.isr.ist.utl.pt/pub/MIRRORS/ftp.suse.com/projects/
    rsync://ftp.isr.ist.utl.pt/suse/projects/

    http://ftp.kddilabs.jp/Linux/distributions/ftp.suse.com/projects/
    rsync://ftp.kddilabs.jp/suse/projects/



  Now you need to enter the mirrors into the database; it could be done using the
  "mb" mirrorbrain tool. (See 'mb help new' for full option list.)

    mb new ftp.isr.ist.utl.pt \
           --http http://ftp.isr.ist.utl.pt/pub/MIRRORS/ftp.suse.com/projects/ \
           --rsync rsync://ftp.isr.ist.utl.pt/suse/projects/

    mb new ftp.kddilabs.jp \
           --http http://ftp.kddilabs.jp/Linux/distributions/ftp.suse.com/projects/ \
           --rsync rsync://ftp.kddilabs.jp/suse/projects/


  The tool automatically figures out the GeoIP location of each mirror by itself.
  But you could also specify them on the commandline.

  If you want to edit a mirror later, use
    mb edit <identifier>

  To simply display a mirror dataset, you'd use 'mb show kddilabs', for instance.

  Finally, each mirror needs to be scanned and enabled:
    mb scan --enable <identifier>

  See the output of 'mb help' for more commands.




- configure Apache:

  - load the Apache modules:
     a2enmod form
     a2enmod dbd
     a2enmod mirrorbrain

  - create a DNS alias for your web host, if needed

  - configure the database adapter (mod_dbd), resp. its connection pool.
    Put the configuration into server-wide context. 

    Config example::
    ------------------------------------------------------------------------
    # for prefork, this configuration is inactive. prefork simply uses 1
    # connection per child.
    <IfModule !prefork.c>
            DBDMin  0
            DBDMax  32
            DBDKeep 4
            DBDExptime 10
    </IfModule>
    ------------------------------------------------------------------------

  - configure the database driver.
    Put this configuration into server-wide OR vhost context. Make the file
    chmod 0640, owned root:root because it will contain the database password.

    Config example::
    ------------------------------------------------------------------------
    # for MySQL:

    DBDriver mysql
    # reconnect=0 is needed with the mysql adapter. It means that connections
    # should not be "reanimated", because prepared statements would be lost anyway,
    # so dead connections should rather be invalidated and new ones made.
    DBDParams "host=localhost, user=wwwrun, pass=12345, dbname=mirrorbrain, reconnect=0"
    # # threaded MPMs only. prefork will have use db connection per process
    
    # or, for PostgreSQL:

    DBDriver pgsql
    # note that the connection string (which is passed straight through to
    # PGconnectdb in this case) looks slightly different - pass vs. password
    DBDParams "host=localhost user=mb password=12345 dbname=mirrorbrain connect_timeout=15"
    ------------------------------------------------------------------------


  - configure mod_mirrorbrain.
    You probably want to reate a vhost (e.g.
    /etc/apache2/vhosts.d/go-oo.mirrorbrain.org.conf) and add the MirrorBrain
    configuration like shown here:

    ------------------------------------------------------------------------
    <VirtualHost your.host.name:80>
        ServerName go-oo.mirrorbrain.org
    
        ServerAdmin webmaster@mirrorbrain.org
    
        DocumentRoot /srv/go-oo/pub/projects
    
        ErrorLog     /var/log/apache2/go-oo.mirrorbrain.org/logs/error_log
        CustomLog    /var/log/apache2/go-oo.mirrorbrain.org/logs/access_log combined

        <Directory /srv/go-oo/pub/projects>
            MirrorBrainEngine On
            MirrorBrainDebug Off
            FormGET On
            MirrorBrainHandleHEADRequestLocally Off
            MirrorBrainMinSize 2048
            MirrorBrainHandleDirectoryIndexLocally On
            MirrorBrainExcludeUserAgent rpm/4.4.2
            MirrorBrainExcludeUserAgent *APT-HTTP*
            MirrorBrainExcludeMimeType application/pgp-keys

            Options FollowSymLinks Indexes
            AllowOverride None
            Order allow,deny
            Allow from all
        </Directory>
    
    </VirtualHost>
    ------------------------------------------------------------------------

  - restart Apache, while watching the error log:
      tail -F /var/log/apache2/*_log &
      rcapache2 restart

    
  - mirror surveillance:
    put this into /etc/crontab:
      -* * * * *     root       /usr/bin/mirrorprobe -t 20 &>/dev/null
    likewise, configure scanning:
      44 0,4,8,12,16,20 * * *   mirrorbrain   mb scan -j 3 -a


  - TODO: describe how to test that the install was successful
    (When testing, consider any excludes that you configured, and which may
    confuse you.)


  - TODO: describe decent logging setup


  - further things that you might want to configure:
     - mod_autoindex_mb, a replacement for the standard module mod_autoindex:
         a2dismod autoindex
         a2enmod autoindex_mb
         Add IndexOptions Metalink Mirrorlist
         (or IndexOptions +Metalink +Mirrorlist, depending on your config)

     - add a link to a CSS stylesheet for mirror lists: 
         MirrorBrainMirrorlistStylesheet "http://static.opensuse.org/css/mirrorbrain.css"
       and for the autoindex:
         IndexStyleSheet "http://static.opensuse.org/css/mirrorbrain.css"
 
     - prepare the metalink hashes. First, add some configuration:
         MirrorBrainMetalinkPublisher "openSUSE" http://download.opensuse.org
         MirrorBrainMetalinkHashesPathPrefix /var/lib/apache2/metalink-hashes/ppc
       install the "metalink" tool from http://metamirrors.nl/metalinks_project
       (openSUSE package called metalink, http://download.opensuse.org/repositories/network:/utilities/)
       create the actual hashes:
         metalink-hasher update -t /var/lib/apache2/metalink-hashes/ppc/srv/ftp/pub/opensuse/ppc -b /srv/ftp/pub/opensuse/ppc /srv/ftp/pub/opensuse/ppc
       add the hashing command to /etc/crontab to be run every few hours.


+++
That's how far the instructions go. I hope they are useful. Please subscribe to
the mirrorbrain mailing list, see http://mirrorbrain.org/communication .
Questions can be answered there, feedback is appreciated.


TODO:

- add wrapper script to run mirrorprobe / scanner as unprivileged user
  and describe how to set it up

    su - mirror -s /bin/bash -c "/usr/bin/scanner.mine -f ftp.isr.ist.utl.pt"
    -*/3 * * * *     root  /usr/bin/mirrorprobe &>/dev/null




Memcache support
================

Memcache support is optional. You should not need it normally, so it is
suggested that you just ignore this. When compiling with memcache support,
-DWITH_MEMCACHE needs to be among the compile flags.
apxs2 -c -Wc,"-DWITH_MEMCACHE -Wall -g" mod_mirrorbrain.c
If you use an apr-util version prior to 1.3, the memcache client support isn't included. Then you'll
need to get and build libapr_memcache, and then you'll probably build mod_mirrorbrain like this:
apxs2 -c -I/usr/include/apr_memcache-0 -lapr_memcache '-Wc,-Wall -DWITH_MEMCACHE -g -D_GNU_SOURCE' mod_mirrorbrain.c

Further steps required for memcache support would be:
- install memcached
- make sure it listens on localhost only (/etc/sysconfig/memcached)
- start it ("/etc/init.d/memcached start")
- configure it to start at boot ("chkconfig -a memcached")
- install mod_memcache
  http://code.google.com/p/modmemcache/
  (openSUSE package apache2-mod_memcache)
  a2enmod memcache

Configuration example:
    <IfModule mod_memcache.c>
        MemcacheServer 127.0.0.1:11211 min=0 smax=4 max=16 ttl=600
    </IfModule>
    <IfModule mod_mirrorbrain.c>
        MirrorBrainMemcached On
        MirrorBrainMemcachedLifetime 1800
    </IfModule>


