<!--toc--> |
|
## Introduction |
|
There are many options to connect CppCMS application to web server: |
|
- Select protocol: you can use FastCGI or SCGI protocols, |
you can also run over HTTP protocol behind proxy. |
|
Recommendation: use FastCGI as it has best support |
over various web servers. |
|
- Application start: it can be started by the web server |
and controlled by it or it can run as independent |
service when web server only connects to it. |
|
- Communication method: you can use Unix domain sockets |
or tcp/ip sockets. For local communication unix sockets |
are preferred. |
|
|
## Assumptions |
|
In all our examples we assume: |
|
- Application's executable placed in `/opt/app/bin/hello` |
- Application's configuration file placed in `/opt/app/etc/config.js` |
- The document root is `/var/www` |
- Our application's URL (script) is `/hello` |
|
## Apache |
|
### Apache, FastCGI |
|
You need to enable at least two modules: `mod_fastcgi` and `mod_alias` |
|
For each case we prepare `mod_fastcgi` configuration file |
and out config.js |
|
#### Apache, FastCGI, Start by Web Server |
|
Apache configuration: |
|
|
FastCgiIpcDir /var/lib/apache2/fastcgi |
# Usually it is given in fastcgi.conf by default |
|
FastCgiServer /opt/app/bin/hello -initial-env CPPCMS_CONFIG=/opt/app/etc/config.js -socket /tmp/hello-fcgi-socket |
# CPPCMS_CONFIG should hold the path to configuration file. |
# Note: you can't pass command line parameter |
# so you pass the location of configuration file |
# via CPPCMS_CONFIG environment variable |
|
FastCGIConfig -maxProcesses 1 -processSlack 1 |
# This is important - we want apache to use only |
# one process as we have cache and many other |
# goodies handled by outsefs |
|
ScriptAliasMatch ^/hello(.*)$ /opt/app/bin/hello$1 |
# We map script "/hello" to our application |
|
AddHandler fastcgi-script /opt/app/bin/hello |
|
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "fastcgi", |
"socket": "stdin" // we use socket given by server |
} |
} |
|
#### Apache, FastCGI, Independent start |
|
Apache configuration: |
|
|
FastCgiIpcDir /var/lib/apache2/fastcgi |
# Usually it is given in fastcgi.conf by default |
|
FastCgiExternalServer /opt/app/bin/hello -socket /tmp/hello-fcgi-socket |
# We provide a socket the application listens on. |
|
ScriptAliasMatch ^/hello(.*)$ /opt/app/bin/hello$1 |
# We map script "/hello" to our application |
|
AddHandler fastcgi-script /opt/app/bin/hello |
|
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "fastcgi", |
"socket": "/tmp/hello-fcgi-socket" |
// Same as in apache config |
} |
} |
|
Now you should run the CppCMS application independently |
as `/opt/app/bin/hello -c /opt/app/etc/config.js` |
|
If you want to use TCP/IP sockets and not Unix one change |
|
- in `FastCgiExternalServer` line parameter `-socket` to `-host 127.0.0.1:8081` |
- in CppCMS config change `"socket": "/tmp/hello-fcgi-socket"` to `"host" : "127.0.0.1", "port" : 8081` |
|
### Apache, SCGI |
|
Apache's `mod_scgi` supports only in-depended/external start and works over TCP/IP sockets, so the configuration is quite simple: |
|
Apache's module configuration: |
|
SCGIMount /hello 127.0.0.1:8081 |
|
We pass the script name as mount point and ip:port as |
point to connect cppcms application. |
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "scgi", |
"host" : "127.0.0.1", |
"port" : 8081 |
} |
} |
|
Now you should run the CppCMS application independently |
as `/opt/app/bin/hello -c /opt/app/etc/config.js` and Apache would connect to it. |
|
## Lighttpd |
|
Lighttpd supports both fastcgi/scgi protocols over unix and tcp/ip sockets. It can start the application for you and use external FastCGI/SCGI application. |
|
### Lighttpd, FastCGI |
#### Lighttpd, FastCGI, Start by Web Server |
|
You should enable mod-fastcgi and then use this Configuration file: |
|
fastcgi.server = ( |
## The script name of the application |
"/hello" => (( |
## Command line to run |
"bin-path" => "/opt/app/bin/hello -c /opt/app/etc/config.js", |
"socket" => "/tmp/hello-fcgi-socket", |
## Important - only one process should start |
"max-procs" => 1, |
"check-local" => "disable" |
)) |
) |
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "fastcgi", |
"socket" : "stdin" // use server's socket |
} |
} |
|
#### Lighttpd, FastCGI, External Start |
|
You should enable mod-scgi and then use this Configuration file: |
|
fastcgi.server = ( |
## The script name of the application |
"/hello" => (( |
"socket" => "/tmp/hello-fastcgi-socket", |
## Important - only one process should start |
"max-procs" => 1, |
"check-local" => "disable" |
)) |
) |
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "fastcgi", |
"socket" : "/tmp/hello-fastcgi-socket" // use server's socket |
} |
} |
|
|
|
If you want to use TCP/IP rather then Unix sockets, replace |
|
- In lighttpd configuration: `"socket" => "/tmp/hello-fastcgi-socket",` by `"host" => "127.0.0.1", "port" => 8081,` |
- In cppcms configuration: `"socket" : "/tmp/hello-fastcgi-socket"`, by `"host": "127.0.0.1" , "port" : 8081,` |
|
|
### Lighttpd, SCGI |
#### Lighttpd, SCGI, Start by Web Server (lighttpd >=1.4.23) |
|
You should enable mod-scgi and then use this Configuration file: |
|
scgi.server = ( |
## The script name of the application |
"/hello" => (( |
## Command line to run |
"bin-path" => "/opt/app/bin/hello -c /opt/app/etc/config.js", |
"socket" => "/tmp/hello-fcgi-socket", |
## Important - only one process should start |
"max-procs" => 1, |
"check-local" => "disable" |
)) |
) |
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "scgi", |
"socket" : "stdin" // use server's socket |
} |
} |
|
|
|
#### Lighttpd, SCGI, External Start |
|
You should enable mod-scgi and then use this Configuration file: |
|
scgi.server = ( |
## The script name of the application |
"/hello" => (( |
"socket" => "/tmp/hello-scgi-socket", |
## Important - only one process should start |
"max-procs" => 1, |
"check-local" => "disable" |
)) |
) |
|
CppCMS configuration: |
|
{ |
"service" : { |
"api" : "scgi", |
"socket" : "/tmp/hello-scgi-socket" // use server's socket |
} |
} |
|
|
|
If you want to use TCP/IP rather then Unix sockets, replace |
|
- In lighttpd configuration: `"socket" => "/tmp/hello-scgi-socket",` by `"host" => "127.0.0.1", "port" => 8081,` |
- In cppcms configuration: `"socket" : "/tmp/hello-scgi-socket"`, by `"host": "127.0.0.1" , "port" : 8081,` |
|
|
## Nginx |
|
Nginx supports only FastCGI protocol with external application start. Nginx's SCGI module is broken as it does not confirm SCGI specifications: it requires rather HTTP response then CGI one. |
|
Also Nginx's fastcgi module require manual generation |
of `SCRIPT_NAME` and `PATH_INFO` variables. |
|
Web Server Configuration under `server` section: |
|
# We should manually create PATH_INFO |
# variable using URL rewriting |
set $path_info ""; |
if ( $fastcgi_script_name ~ ^/hello(.*)$ ) { |
set $path_info $1; |
} |
|
# Specify UTL to match |
location ~ ^/hello.*$ { |
# Socket to communicate |
fastcgi_pass unix:/tmp/hello-fcgi-socket; |
|
# All supported CGI variables |
fastcgi_param QUERY_STRING $query_string; |
fastcgi_param REQUEST_METHOD $request_method; |
fastcgi_param CONTENT_TYPE $content_type; |
fastcgi_param CONTENT_LENGTH $content_length; |
|
fastcgi_param SCRIPT_NAME /hello; |
fastcgi_param PATH_INFO $path_info; |
fastcgi_param REQUEST_URI $request_uri; |
fastcgi_param DOCUMENT_URI $document_uri; |
fastcgi_param DOCUMENT_ROOT $document_root; |
fastcgi_param SERVER_PROTOCOL $server_protocol; |
|
fastcgi_param GATEWAY_INTERFACE CGI/1.1; |
fastcgi_param SERVER_SOFTWARE nginx; |
|
fastcgi_param REMOTE_ADDR $remote_addr; |
fastcgi_param REMOTE_PORT $remote_port; |
fastcgi_param SERVER_ADDR $server_addr; |
fastcgi_param SERVER_PORT $server_port; |
fastcgi_param SERVER_NAME $server_name; |
} |
|
|
And the usual CppCMS's config: |
|
{ |
"service" : { |
"api" : "fastcgi", |
"socket" : "/tmp/hello-fcgi-socket" |
} |
} |
|
Of course the CppCMS's service should be started independently. |
|
|
