Quickstart Tutorial

Introduction

This tutorial shows you how to:

  • install GX on your system
  • create a GX application using the gx-build command line tool
  • configure your Apache2 / mod_perl 2.x webserver to run a GX application

Installing GX

Manual Installation

Download the latest GX distribution, unpack it, go into the unpacked directory and type:

perl Makefile.PL
make
make test

If everything went fine, type:

make install

This will install the GX modules and scripts on your system. Usually, you will need to be root to do this.

Creating an Application

The easiest way to create a new GX application is to use the gx-build command line tool, which is part of the GX distribution. To begin, go to a suitable working directory, for example /srv/www, by typing:

cd /srv/www

Make sure that you have write access for your chosen directory, then type:

gx-build MyApp --engine Apache2

This will create a skeleton GX application named "MyApp" in the current directory. The --engine Apache2 option tells GX to create a mod_perl adaptor for the application.

Configuring Apache

First, make sure that mod_perl is enabled on your Apache web server, for example by typing (as root):

apache2ctl -M

This will print a list with the modules loaded by Apache. If "perl_module" is not in that list, add the following directive to your Apache's configuration file:

LoadModule perl_module modules/mod_perl.so

This instructs Apache to load the mod_perl DSO (Dynamic Shared Object). Please note that you might have to adjust the specified path. After adding the directive, run apache2ctl -M again to check if everything is working as expected.

Now add the following configuration directives to your Apache's configuration file:

<VirtualHost *:80>

ServerName localhost

DocumentRoot /srv/www/MyApp/public

<Directory /srv/www/MyApp/public>
Order Deny,Allow
Allow from All
</Directory>

PerlOptions +Parent

PerlSwitches -I /srv/www/MyApp/lib

PerlModule MyApp

<Location />
SetHandler perl-script
PerlResponseHandler MyApp
DirectorySlash Off
</Location>

<Location /static>
SetHandler None
</Location>

<Location /favicon.ico>
SetHandler None
</Location>

<Location /error>
SetHandler None
</Location>

</VirtualHost>

Please refer to the official mod_perl documentation for a detailed description of the mod_perl-specific configuration directives used above.

Starting the Application

Finally, start your Apache server, for example on openSUSE 11.2 by typing:

/etc/init.d/apache2 start

Open you favorite web browser and go to http://localhost/. You should now see your application's welcome page. If not, check your Apache's error log to see what went wrong.