Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Gantry::Docs::QuickStaUser)Contributed Perl DocumenGantry::Docs::QuickStart(3)

Name
       Gantry::Docs::QuickStart	- Getting your first Gantry app	up and running

Off and	running
       The easiest way to build	a Gantry app is	with bigtop:

	   bigtop -n AppName 'book(title,pages:int4)<->author(name)'

       Choose a	suitable application name and list the tables you've already
       thought of, including their columns.  When you think of more tables and
       columns later, they will	be easy	to add.	 To learn more about this
       kickstart syntax	see Bigtop::ScriptHelp::Style::Kickstart.

       If you have sqlite in your path,	bigtop will build a database for you.
       Then all	you need to do is change to the	directory it made for your app
       and start the stand alone server.

	   cd AppName
	   ./app.server

       If you don't use	sqlite (or bigtop could	not find it in your path),
       change to the directory bigtop built for	you.  Create a database	called
       app.db with your	database engine, populate the database,	and start the
       app.server.  With Postgres that looks like this:

	   cd AppName
	   createdb app.db -U postgres
	   psql	app.db -U regular_user < docs/schema.postgres
	   ./app.server	-d Pg -u regular_user -p password

       For MySQL, try this instead:

	   cd AppName
	   msyqladmin create app_db -u root -p
	   mysql -u root -p app_db < docs/schema.mysql
	   ./app.server	-d=mysql --u=regular_user -p='secret' -n=app_db

       Then the	app is running,	you can	view it	by pointing your browser to
       any of the URLs app.server printed on startup.

A Simple Greeting
       This section is for those who prefer a less magical experience.

       All you need for	a gantry app is	a module which uses Gantry and has a
       method called do_something (usually do_main is a	good first choice):

	   package HiWorld;
	   use strict; use warnings;

	   use base 'Gantry';

	   sub do_main {
	       my $self	= shift;

	       return "Hello, Rob";
	   }

	   1;

       I'll store this module in /home/myhome/lib/HiWorld.pm.  I'll need to
       set that	lib path with a	use lib	below.

Stand Alone Server Deployment
       If you have HTTP::Server::Simple	installed, you may choose to deploy
       your application	through	it.  This is useful for	kick starting
       development.  See below for more	permanent means	of deployment.

       A stand alone Gantry application	is an executable script	which
       leverages Gantry::Server	(which in turn uses HTTP::Server::Simple).
       This one	is enough for our small	demo:

	   #!/usr/bin/perl
	   use strict;

	   use Gantry::Server;

	   use lib '/home/myhome/lib';

	   use HiWorld qw{ -Engine=CGI -TemplateEngine=Default };

	   my $cgi = Gantry::Engine::CGI->new();

	   $cgi->add_location( '/', 'HiWorld' );

	   my $port   =	shift || 8080;
	   my $server =	Gantry::Server->new( $port );

	   $server->set_engine_object( $cgi );
	   $server->run();

       If you used Bigtop, as in the first section of this document, it	made
       "app.server" which is similar to	this one.

CGI Deployment
       To deploy using CGI, create the following script	in a servable cgi-bin
       directory (remember to make sure	it is executable):

	   #!/usr/bin/perl
	   use strict;

	   use CGI::Carp qw( fatalsToBrowser);

	   use lib '/home/myhome/lib';

	   use HiWorld qw{ -Engine=CGI -TemplateEngine=Default };

	   my $cgi = Gantry::Engine::CGI->new();

	   $cgi->add_location( '/', 'HiWorld' );

	   $cgi->dispatch();

       Then point your browser to the script.

       If you used Bigtop to generate the application, as shown	in the first
       section above, it made "app.cgi"	for you.  You can deploy to CGI	by
       copying that file into your web server's	"cgi-bin" directory, if	you
       also:

       install the app
	   The HiRob.pm	module must be installed somewhere in the @INC path,
	   or you must add a "use lib" statement in your CGI script which
	   includes the	directry where the module lives.

       set permissions correctly
	   First, the web server must be able to read the build	directory and
	   its sub directories.	 (If you have an sqlite	database, you must
	   make	both the database and the build	directory writable by the web
	   server.)

       beware of selinux
	   Tools like selinux exist to keep people from	accessing things.  As
	   such, they will probably block users	from seeing things in your
	   build directory via a web server.  Either disable it, or move
	   things to appropriate places	it allows the web server to access.

       See "What is Gantry::Conf" and "How do I	use Gantry::Conf under
       CGI/FastCGI" in Gantry::Docs::FAQ for information on switching the CGI
       script to a different database.

mod_perl Deployment
       To use mod_perl,	you must have permission to modify the httpd.conf for
       your web	server and to restart it.  Here	is the virtual host I created
       for the greeting	application:

	   <VirtualHost	hiworld.devel.example.com>

	       ServerName   hiworld.devel.example.com
	       DocumentRoot /home/myhome/html/play
	       CustomLog    /home/myhome/logs/combined.log combined
	       ErrorLog	    /home/myhome/logs/hiworld.err

	       Include /home/myhome/html/play/hiworld.conf

	   </VirtualHost>

       This throws the real config work	to hiworld.conf.  Mine assumes
       mod_perl	1.3.  Here it is:

	   <Perl>
	       #!/usr/bin/perl

	       use lib '/home/pcrow/srcgantry/play';

	       use HiWorld qw{ -Engine=MP13 -TemplateEngine=Default };
	   </Perl>

	   <Location /hello>
	       SetHandler  perl-script
	       PerlHandler HiWorld
	   </Location>

       After restarting	the server, I can point	my browser to

	   http://hiworld.devel.example.com/hello

       to see the greeting.

       If you are using	mod_perl 2, simply change the use statement to:

	       use HiWorld qw{ -Engine=MP20 -TemplateEngine=Default };

       (i.e. replace MP13 with MP20)

       Note that if other Gantry apps are running in the same server instance,
       they may	fight over which template engine to use.  Generally, the first
       app to put in a use statement for its base module chooses the template
       engine.	We don't mind this since we always use TT.  Even after you
       have chosen TT, you can turn it off by adding statements	like these to
       the top of your do_* method.

	   $self->content_type(	'text/xml' );
	   $self->template_disable( 1 );

What To	Do Now
       Once you	have your first	app running, as	shown above, you are ready to
       move on in the following	sequence of documents:

       1.  Gantry::Docs::Tutorial

       2.  Bigtop::Docs::Tutorial

       After those, you	probably want Gantry::Docs::FAQ,
       Gantry::Docs::Cookbook, or Bigtop::Docs::Cookbook.

Author
       Phil Crow <crow.phil@gmail.com>

Copyright and License
       Copyright (c) 2006-7, Phil Crow.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.6 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.24.1			  2017-07-02	   Gantry::Docs::QuickStart(3)

Name | Off and running | A Simple Greeting | Stand Alone Server Deployment | CGI Deployment | mod_perl Deployment | What To Do Now | Author | Copyright and License

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Gantry::Docs::QuickStart&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help