Installing Groogle

Before you start

Your server and clients

Before you start, bear in mind the following:

  • Groogle will talk to your repository **A LOT**. For best results make sure that the network link between your repository and the server Groogle is hosted on is fast, preferably on the same LAN.
  • Groogle does a lot of processing. When it's busy it uses a lot of disk IO, a fair bit of network IO and a bucket of CPU. It also caches data heavily so expect it to use up a fair bit of disk space (think several GB's for a heavily used installation). Don't try putting it on your old 386 with an old and slow 512MB hard disk. It won't work out for you.
  • Groogle is designed to be deployed on Linux. Deploying it on Windows is not supported. Some modules that Groogle depends on, particularly those required for the Groogle Daemon, don't build on Windows. You might be able to install it on other Unix-like platforms, but Linux (in-particular RHEL/CentOS 5+) will give you the easiest ride. If you only have Windows hosts to install on, then consider using a virtual machine to host Groogle. The example commands in this installation guide are for RHEL/CentOS 5+.
  • Groogle makes heavy use of CSS and javascript. Browser support for some of the features is patchy. Currently you'll need one of the following browsers:
    • Firefox >= 3.0
    • Internet Explorer >= 7
    • Chrome >= 8
    • Safari >= 8
    • Opera >= 10
    If you are using another browser, it may work just fine but there's no guarantees. Most Webkit browsers should now work with Groogle. There's no plans to support anything older than the above browser versions.
  • A browser with a fast javascript engine is a very good idea.

Upgrading PHP

RHEL/CentOS 5 ship with php version 5.1.6 but groogle requires at least version 5.2.6. Update to release RHEL/CentOS 5.6 to upgrade to PHP 5.3.

If you want to stick with a release older than 5.6, updated PHP packages can be found in CentOS testing. Follow the following link for instructions on upgrading.

http://wiki.centos.org/HowTos/PHP_5.1_To_5.2

Note that once you have upgraded PHP you'll need rebuild your PEAR/PECL modules before they will work and you will also need to restart your web server.

Enabling the RPMforge repository

RHEL/Centos 5 don't ship the memcache deamon in the default repository set. A memory caching daemon is optional and can be disabled but it will greatly improve database performance and so is recommended. The RPMforge repository contains the optional memcache daemon and its perl dependencies. To install and enable it, run the following: # rpm -Uhv http://apt.sw.be/redhat/el5/en/i386/rpmforge/RPMS/rpmforge-release-0.3.6-1.el5.rf.i386.rpm

Base installation

  1. Install your linux host server. RHEL/CentOS 5 or newer for the easiest install. The example commands given here are for these platforms.
  2. Install some dependant libraries and components for Groogle. # yum install httpd php mysql-server php-gd php-pdo php-pear php-pear-DB php-pear-Log php-pear-MDB2 php-mysql memcached mod_ssl php-xml php-bcmath
  3. Install the Groogle RPM/unpack the tarball. You will also need some build tools required to compile the pear modules. The RPM will pull these dependencies in. You'll need to ignore signatures since the groogle RPM isn't signed.
    NOTE: The version of yum which ships with a CentOS 5.0 installation doesn't support --nogpgcheck. Make sure you update your distribution to the latest release via yum upgrade before continuing.
    # yum localinstall --nogpgcheck groogle-*.noarch.rpm
  4. Install the rest of the build tools needed (gcc): # yum install gcc
  5. Install some build dependencies: # yum install zlib-devel php-devel
  6. Install pear and pecl modules: # pecl install memcache
    # pear install Auth
    # pear install Text_Diff
    # pear install System_Daemon
    # pear install HTTP
  7. Create the file /etc/php.d/memcache.ini and add the following: ; Enable the memcache extension module extension=memcache.so
  8. Install the doctrine ORM: # pear channel-discover pear.doctrine-project.org
    # pear install pear.doctrine-project.org/Doctrine-1.2.2.tgz
  9. Enable and start the memory caching daemon # chkconfig memcached on
    # service memcached start
  10. Enable and start the mysql server # chkconfig mysqld on
    # service mysqld start
  11. Change to the groogle db directory and run the patchdb.sh script. If you require any database connection parameters, such as a root password, you can specify them as parameters to the patchdb.sh script. The parameters take the same form as the mysql command line client. # cd /var/www/groogle/db/
    # ./patchdb.sh -u root
  12. Delete the anonymous entries from the mysql user table, else groogle won't be able to talk to its own database. # mysql -u root
    mysql> use mysql
    Reading table information for completion of table and column names
    You can turn off this feature to get a quicker startup with -A

    Database changed

    mysql> delete from user where user='';
    Query OK, 2 rows affected (0.00 sec)

    mysql> flush privileges;
    Query OK, 0 rows affected (0.00 sec)

    mysql> exit
    Bye
  13. Edit your /etc/php.ini file and increase your resource limits as follows: max_execution_time = 300
    max_input_time = 300
    memory_limit = 128M
  14. Restart the webserver. # service httpd restart
  15. Generate the groogle daemon init.d script and enable it during system startup. # cd /var/www/groogle/htdocs
    # php groogle_daemon.php --write-initd
    # chkconfig --add groogled
    # chkconfig groogled on
    # service groogled start
  16. Generate the groogle checkout daemon init.d script and enable it during system startup. # cd /var/www/groogle/htdocs
    # php checkout_daemon.php --write-initd
    # chkconfig --add grooglecheckoutd
    # chkconfig grooglecheckoutd on
    # service grooglecheckoutd start

Adding subversion support

Groogle supports working against live subversion repositories. To add support install the pecl svn module:

  1. Install the development headers: # yum install subversion-devel apr-devel neon-devel
  2. Compile and install the pecl svn module: # pecl install svn
  3. Enable the svn module by creating the file /etc/php.d/svn.ini and adding the following: ; Enable the pecl svn extension module
    extension=svn.so
  4. Restart the webserver. # service httpd restart

See the configuration section for configuring subversion support.

Adding archive upload support

Groogle also supports working with uploaded zip and tar.gz archives. To add support, install the File_Archive pear module:

  1. Install the File_Archive module. # pear install File_Archive
  2. Restart the webserver. # service httpd restart

See the configuration section for configuring archive upload support.

Configuring Groogle

Configuration files for Groogle can be found under htdocs/conf within your Groogle installation directory (/var/www/groogle/ for RPM versions). Each file consists of a set of php variables which can be used to configure Groogle. Go through each of these to configure Groogle for your environment.

Authentication

Authentication can be configured from the conf/auth.php file. Groogle uses the Pear::Auth module for configuring authentication. Consult the Pear::Auth package documentation for configuring the auth_type and auth_options parameters found in this file.

Caching support

The conf/cache.php file lists the location of the cache directories Groogle will use. If you want the cache files to be written elsewhere, then update these paths to match the new location. Groogle won't automatically create the directories, so you'll have to move the existing ones to the new location (or create new ones with the correct permissions).

Comparisons

The conf/compare.php file configures how Groogle will handle comparing repositories.

Database configuration

The conf/db.php file configures the database connection settings for Groogle. The default value is correct for a normal installation. If you want to change hosts or passwords then you'll need to update this file too.

E-mail notifications

The conf/email.php file contains configuration for enabling e-mail notifications to Groogle users.

File upload support

The conf/fileupload.php file contains configuration used if file archive upload or patch support is enabled.

Groogle daemon support

The conf/groogled.php file contains configuration used for the groogle daemon, such as host and port.

Internationalisation

The conf/i18n.php file contains configuration used for internationalisation support, such as character encoding, etc.

Logging

The conf/log.php file contains configuration for the Pear log library. Unless you are in trouble, the defaults here are sufficient.

Memory cache support

The conf/memcache.php file contains configuration for optionally using a memcache server for caching database queries and results. You can enable or disable memcache support here, or change the host on which the memcache server can be found.

Supported resource types

The conf/resourcetypes.php file contains configuration flags to indicate which resource types Groogle will allow (i.e. file upload support, subversion support, etc). Modify this file to enable and disable support for the various resource types.

Server configuration

The conf/server.php file contains configuration files for your server, such as the full hostname, ports, whether to use https, data limits, etc. Modify this file to reflect your installation environment.

Subversion support

The conf/svn.php file contains some configuration options for working with subversion servers. It allows for transparent URL transformations, client side transformations.

Template configuration

The conf/template.php file contains configuration options for stylesheets used for the UI. There is only one stylesheet set currently for Groogle so there's no need to change these values.

Checking your installation

Groogle provides some simple self-diagnostics to check that your installation is correct and complete. To run a diagnostic check, point a browser at your Groogle installation. If your installation check succeeds you will be automatically redirected to the Groogle login page. If not, some instructions on correcting any installation problems will be provided.

Once you see the login page your installation is complete!

Have fun!