Creating Project with Fano CLI

Scaffolding CGI project directory structure

To scaffold project structure using Fano framework, run with --project-cgi command line options

$ fanocli --project-cgi=[project-name]

For example, following command will cause a new project created in directory name test-fano inside current directory.

$ fanocli --project-cgi=test-fano

Scaffolding FastCGI project directory structure with Apache mod_fcgid module

To scaffold FastCGI project structure using Fano framework that employ Apache mod_fcgid, run with --project-fcgid command line options

$ fanocli --project-fcgid=[project-name]

For example, following command will cause a new FastCGI project created in directory name test-fano-fcgi inside current directory.

$ fanocli --project-fcgid=test-fano-fcgi

See Deploy as FastCGI application for information on how to setup FastCGI application to work with various web server.

Scaffolding FastCGI project directory structure

To scaffold FastCGI project structure using Fano framework, run with --project-fcgi command line options

$ fanocli --project-fcgi=[project-name]

For example, following command will cause a new FastCGI project created in directory name test-fano-fcgi inside current directory.

$ fanocli --project-fcgi=test-fano-fcgi

Additionally, you can set --host and --port where FastCGI will listen. If omitted, 127.0.0.1 and 20477 will be used as host and port respectively.

$ fanocli --project-fcgi=test-fano-fcgi --host=192.168.2.1 --port=4040

Generated project files are mostly similar to --project-cgi output, except that src/app.pas, and src/bootstrap.pas which will generate a daemon FastCGI web application. See Deploy as FastCGI application for information on how to setup FastCGI application to work with various web server.

Difference between FastCGI application created with --project-fcgid and --project-fcgi, first command will create FastCGI application which its process is managed by Apache mod_fcgid module while latter must be run independently using Apache mod_proxy_fcgi or Nginx with reverse proxy.

Scaffolding SCGI project directory structure

To scaffold SCGI project structure using Fano framework, run with --project-scgi command line options

$ fanocli --project-scgi=[project-name]

For example, following command will cause a new SCGI project created in directory name test-fano-scgi inside current directory.

$ fanocli --project-scgi=test-fano-scgi

Additionally, you can set --host and --port where SCGI will listen. If omitted, 127.0.0.1 and 20477 will be used as host and port respectively.

$ fanocli --project-scgi=test-fano-scgi --host=192.168.2.1 --port=4040

Generated project files are mostly similar to --project-fcgi output but for SCGI protocol. See Deploy as SCGI application for information on how to setup SCGI application to work with various web server.

Scaffolding uwsgi project directory structure

To create web application that use uwsgi protocol, use --project-uwsgi parameter. Other parameters are similar to SCGI or FastCGI project above.

See Deploy as uwsgi application for information on how to setup uwsgi application to work with various web server.

Scaffolding libmicrohttpd http project directory structure

To create web application that use http protocol using libmicrohttpd, use --project-mhd parameter. Other parameters are similar to SCGI, FastCGI or uwsgi project above.

It will add conditional define -dLIBMICROHTTPD in build.cfg which cause libmicrohttpd to be linked with application.

You need to install libmicrohttpd development package otherwise you get linking error.

See Deploy as standalone web server for information on how to setup http application to work as a standalone web server or run behind various reverse proxy web server.

Add https support

Inside generated project directory, you can find that src/app.pas will have following commented code

//svrConfig.useTLS := true;
//svrConfig.tlsKey := '/path/to/ssl/cert/key';
//svrConfig.tlsCert := '/path/to/ssl/cert/cert';

If you want to support https, you need to uncomment those three lines of codes and set correct path for SSL certificate files. You need to make sure that they are readable by application.

Scaffolding http project directory structure

To create http web application that use Free Pascal built-in http server,TFpHttpServer class, use --project-http parameter. Other parameters are similar to SCGI, FastCGI or uwsgi project above.

See Deploy as standalone web server for information on how to setup http application to work as a standalone web server or run behind various reverse proxy web server.

Scaffolding http project with Indy

To create http web application that use Indy http server,TIdHttpServer class, use --project-indy parameter. Other parameters are similar to SCGI, FastCGI or uwsgi project above.

Make sure you set INDY_DIR environment variable to point to where Indy directory installation before compilation.

$ export INDY_DIR="/path/to/indy"

or you can set it in .env file which will be loaded when you run build script. Please note that you should not add trailing slash, so use

$ export INDY_DIR="/path/to/indy"

and not

$ export INDY_DIR="/path/to/indy/"

When you use Indy, you must aware of Indy memory leak issue.

See Deploy as standalone web server for information on how to setup http application to work as a standalone web server or run behind various reverse proxy web server.

Use Fano Framework specific release version

By default, when you use any --project-* option, it will use latest commit of master branch of Fano Framework repository. To use Fano Framework specific release version when creating project, add --fano-ver=[VER] option, [VER] is string that contains specific release tag to use. For example, to use Fano Framework version 1.0.0, run following command.

$ fanocli --project-scgi=example.fano --fano-ver=v1.0.0

Visit Fano Framework releases page for complete list of release versions.

Setup application configuration when creating project

All commands for creating project, for example, --project-cgi, --project-fcgi, --project-scgi, etc, accept additional parameter --config=[configType] where [configType] is either ini or json.

If --config is set, then during project creation, it generates application configuration files and register application configuration to dependency container. If --config is set but its value is empty string, json is assumed.

$ fanocli --project-fcgi=test-fano --config=ini

Read Application Configuration for more information.

Add session support

Use --with-session to add session support. Read Session documentation for more information.

$ fanocli --project-fcgi=test-fano --config=ini

Add middleware support

Use --with-middleware to add middleware support. Read Middleware documentation for more information.

Add CSRF support

Use --with-csrf to add CSRF support. Read Cross-Site Request Forgery (CSRF) protection for more information.

Add logger dependencies

Use --with-logger to add logger dependencies to service container. Read Using Loggers for more information.

Unrelated commit histories issue

--project-* command line options creates Git repository and initial commit for you automatically. This behavior may cause problem if you already create remote repository and try to merge local repository with remote one. Git may refuse to merge because they have unrelated commit histories.

To workaround this problem, you can run git merge with option --allow-unrelated-histories or create project directory structure without Git repository (--no-git).

$ fanocli --project-cgi=test-fano --no-git

or create project directory with Git repository but without creating initial commit (--no-initial-commit)

$ fanocli --project-cgi=test-fano --no-initial-commit

--no-git options is provided to enable you to initialize Git repository manually.

After project directory is constructed, you need to execute following commands,

$ cd test-fano
$ git init
$ git submodule add https://github.com/fanoframework/fano.git vendor/fano
$ git add .
$ git commit -m "Initial commit"

--no-initial-commit is provided to enable you to commit Git repository manually. So you can merge local repository with a remote repository before running git commit. After project directory is constructed, you need to execute following commands,

$ cd test-fano
$ git commit -m "Initial commit"

Use libcurl in application

If you want to use curl-based HTTP client such as THttpGet class, use --with-curl parameter. It adds conditional define -dLIBCURL in defines.cfg file which causing libcurl library linked with application.

$ fanocli --project-scgi=hello --with-curl

You need to install libcurl development package otherwise you get missing libcurl error.

Explore more