Getting Started basic CGI application

Following document explains minimum steps required to setup a working Fano CGI web application on development machine.

Requirement

Linux or FreeBSD
Free Pascal >= 3.0
git
Apache 2.4
mod_cgi or mod_cgid
mod_rewrite
Fano CLI
Working Internet connection.
Root privilege (for setting up virtual host).

Install Fano CLI

Install Fano CLI as described in Installation section of Scaffolding with Fano CLI documentation.

Create application

Make sure all requirements above are met. Run

$ fanocli --project-cgi=Hello
$ cd Hello
$ fanocli --controller=Home --route=/
$ ./build.sh
$ sudo fanocli --deploy-cgi=hello.fano

Run it from browser

Open web browser and go to http://hello.fano. You should see Home controller text is printed in browser. Congratulations, your application is working. If you do not see text is printed, read What could go wrong section below.

Following video shows step by step creating Fano Framework web application project.

Command walkthrough

Let us take a look at each command above to understand what it does.

Following command tells Fano CLI to create CGI web application project in Hello directory. Directory must not exist. Read Creating Project with Fano CLI for creating different web application project (FastCGI, SCGI, uwsgi or http).

$ fanocli --project-cgi=Hello

We change active directory to newly created Hello directory.

$ cd Hello

Create controller name HomeController.pas that will handle request to route /. For more information regarding route, read Working with Router.

$ fanocli --controller=Home --route=/

Without --route=/, by default, Fano CLI will create route same as lower case of controller’s name, i.e, /home. If you omit --route=/ then you can only access HomeController using URL http://hello.fano/home instead of http://hello.fano.

Compile application

$ ./build.sh

Setup a virtual host for domain hello.fano and associate it with our CGI application binary.

$ sudo fanocli --deploy-cgi=hello.fano

--deploy-cgi modifies web server configuration and reload it. That is why you need to use sudo command. Read Deployment for deploying different protocol web application project (FastCGI, SCGI, uwsgi, http).

Project directory walkthrough

Fano Framework has no opinion about your project directory structure. You can structure your project directories and files the way you like. However, Fano CLI creates several files and directories that follows certain assumptions.

Directories

src, application project source code directory
bin, compiled binaries output directory,
config, application configuration directory
resources, application resources directory, such as HTML templates, SCSS, etc.
storages, application runtime-generated files directory, such as session files, logs etc.
tools, helper shell scripts directory, such as scripts to clean compiled binaries.
public, application document root directory where public resources resides such as images, cascade stylesheets, JavaScripts files.

Files

Main program source code is src/app.pas.
Main unit src/bootstrap.pas glues all modules.
Home controller HomeController.pas in src/App/Home/Controllers is code that prints Home controller text.
Include file src/Routes/Home/route.inc associates default URL / with home controller.
Include file controllers.dependencies.inc in src/Dependencies directory, registers factory class for home controller.

What could go wrong

Browser downloads application binary

When you visit http://hello.fano URL, browser displays confirmation dialog to download application binary instead of displaying Home Controller text. This is most likely because mod_cgi or mod_cgid is not enabled. Both modules are installed by default on Apache 2 but are not enabled.

To remedy, you need to enable it and restart Apache. For example, to enable mod_cgi module

$ sudo a2enmod cgi
$ sudo systemctl restart apache2

Replace cgi with cgid if you want to enable mod_cgid module instead.

Explore more

Documentation