FastCGI Web application skeleton using Fano Framework, Pascal web application framework. This application is listen to Unix Domain Socket.
This project is generated using Fano CLI command line tools to help scaffolding web application using Fano Framework.
- Free Pascal >= 3.0
- libcurl development
- Web Server (Apache, nginx)
- Fano Web Framework
$ git clone git@github.com:fanofamework/fano-app.git --recursive
$ ./tools/config.setup.sh
$ ./build.sh
Make sure Free Pascal is installed. Run
$ fpc -i
If you see something like Free Pascal Compiler version 3.0.4
, you are good to go.
Clone this repository
$ git clone git@github.com:fanofamework/fano-app.git --recursive
--recursive
is needed so git also pull Fano repository.
If you are missing --recursive
when you clone, you may find that vendor/fano
directory is empty. In this case run
$ git submodule update --init
To update Fano to its latest commit, run
$ git checkout master && git submodule foreach --recursive git pull origin master
Above command will checkout to master
branch of this repository and pull latest update from master
branch of Fano repository.
Copy *.cfg.sample
to *.cfg
.
Make adjustment as you need in build.cfg
, build.prod.cfg
, build.dev.cfg
and run build.sh
shell script (if you are on Windows, then build.cmd
).
These *.cfg
files contain some Free Pascal compiler switches that you can turn on/off to change how executable is compiled and generated. For complete
explanation on available compiler switches, consult Free Pascal documentation.
Also copy src/config/config.json.sample
to src/config/config.json
and edit
configuration as needed. For example, you may need to change baseUrl
to match your own base url so JavaScript or CSS stylesheets point to correct URL.
$ cp config/config.json.sample config/config.json
$ cp build.prod.cfg.sample build.prod.cfg
$ cp build.dev.cfg.sample build.dev.cfg
$ cp build.cfg.sample build.cfg
$ ./build.sh
tools/config.setup.sh
shell script is provided to simplify copying those
configuration files. Following shell command is similar to command above.
$ ./tools/config.setup.sh
$ ./build.sh
By default, it will output binary executable in bin
directory.
To build for different environment, set BUILD_TYPE
environment variable.
$ BUILD_TYPE=prod ./build.sh
Build process will use compiler configuration defined in vendor/fano/fano.cfg
, build.cfg
and build.prod.cfg
. By default, build.prod.cfg
contains some compiler switches that will aggressively optimize executable both in speed and size.
$ BUILD_TYPE=dev ./build.sh
Build process will use compiler configuration defined in vendor/fano/fano.cfg
, build.cfg
and build.dev.cfg
.
If BUILD_TYPE
environment variable is not set, production environment will be assumed.
Compilation will output executable to directory defined in EXEC_OUTPUT_DIR
environment variable. By default is bin
directory.
$ EXEC_OUTPUT_DIR=/path/to/public/dir ./build.sh
Compilation will use executable filename as defined in EXEC_OUTPUT_NAME
environment variable. By default is app.cgi
filename.
$ EXEC_OUTPUT_NAME=index.cgi ./build.sh
Run example Fano FastCGI application
$ ./bin/app.cgi
By default it will listen on Unix domain socket /tmp/fano-fcgi-unix.sock
file.
You need to make sure /tmp/fano-fcgi-unix.sock
permission is writeable
by web server.
Setup a virtual host. Please consult documentation of web server you use.
You need to use Apache 2.4 and to have mod_proxy_fcgi
installed and loaded. This module is Apache's built-in module, so it is very likely that you will have it with your Apache installation. You just need to make sure it is loaded. For example, on Debian,
$ sudo a2enmod proxy_fcgi
$ sudo systemctl restart apache2
Create virtual host config and add ProxyPassMatch
, for example
<VirtualHost *:80>
ServerName www.example.com
DocumentRoot /home/example/public
<Directory "/home/example/public">
Options +ExecCGI
AllowOverride FileInfo
Require all granted
</Directory>
ProxyRequests Off
ProxyPass /css !
ProxyPass /images !
ProxyPass /js !
ProxyPassMatch ^/(.*)$ "unix:/tmp/fano-fcgi-unix.sock|fcgi://127.0.0.1"
</VirtualHost>
Last four line of virtual host configurations basically tell Apache to serve any
files inside css
, images
, js
directly otherwise pass it to our application.
Hostname after fcgi://
are ignored by mod_proxy_fcgi
.
On Debian, save it to /etc/apache2/sites-available
for example as fano-fcgi-unix.conf
Enable this site and restart Apache
$ sudo a2ensite fano-fcgi-unix.conf
$ sudo systemctl restart apache2
If Apache returns HTTP 503 Service Unavailable
and you get following similar messages in error log
[Fri Jun 28 15:46:52.111034 2019] [proxy:error] [pid 18974] (13)Permission denied: AH02454: FCGI: attempt to connect to Unix domain socket /tmp/fano-fcgi-unix.sock (127.0.0.1) failed
then make sure that socket file is writeable by user where Apache runs.
If you get following message when running application,
ESocketError: Binding of socket failed: /tmp/fano-fcgi/fano-fcgi-unix.sock
Delete /tmp/fano-fcgi/fano-fcgi-unix.sock
first then re-run application.
If you run Debian 9 based distribution, each user now has private /tmp directory, which may cause problem because Apache cannot find our socket file. The easiest workaround to this problem for development machine is just to edit /etc/systemd/system/apache2.service
and replace PrivateTmp=true
with PrivateTmp=false
and restart Apache service.
The proper way is of course to setup socket file which accessible both our application and web server unsing for example shell script.
You need to deploy only executable binary and any supporting files such as HTML templates, images, css stylesheets, application config.
Any pas
or inc
files or shell scripts is not needed in deployment machine in order application to run.
So for this repository, you will need to copy public
, Templates
, config
and storages
directories to your deployment machine. make sure that
storages
directory is writable by web server.
When running build.sh
script, you may encounter following warning:
/usr/bin/ld: warning: public/link.res contains output sections; did you forget -T?
This is known issue between Free Pascal and GNU Linker. See FAQ: link.res syntax error, or "did you forget -T?"
However, this warning is minor and can be ignored. It does not affect output executable.
Sometime Free Pascal can not compile your code because, for example, you deleted a unit source code (.pas) but old generated unit (.ppu, .o, .a files) still there or when you switch between git branches. Solution is to remove those files.
By default, generated compiled units are in bin/unit
directory.
But do not delete README.md
file inside this directory, as it is not being ignored by git.
$ rm bin/unit/*.ppu
$ rm bin/unit/*.o
$ rm bin/unit/*.rsj
$ rm bin/unit/*.a
Following shell command will remove all files inside bin/unit
directory except
README.md
file.
$ find bin/unit ! -name 'README.md' -type f -exec rm -f {} +
tools/clean.sh
script is provided to simplify this task.
Free Pascal supports Windows as target operating system, however, this repository is not yet tested on Windows. To target Windows, in build.cfg
replace
compiler switch -Tlinux
with -Twin64
and uncomment line #-WC
to
become -WC
.
While you can use Lazarus IDE, it is not mandatory tool. Any text editor for code editing (Atom, Visual Studio Code, Sublime, Vim etc) should suffice.