CppCMS configuration file is used to define different |
aspects of the process that may be changes without recompiling |
an application. |
|
## CppCMS Server API -- `server.api` |
|
### Setting API |
|
This parameter is mandatory. CppCMS supports three most popular web server APIs: FastCGI, SCGI and CGI. Values of `server.api` are "fastcgi", "scgi", and "cgi" accordingly. |
|
For example: |
|
server.api = "fastcgi" |
|
### Choosing API |
|
[FastCGI](http://www.fastcgi.com) is the most reliable and recommended API. It has best web servers support and usually has most stable implementations. |
|
_Notes:_ `libcppcms` should be compiled with fastcgi library. |
|
[SCGI](http://python.ca/scgi/protocol.txt) is simple alternative to FastCGI. It is quite common due to very simple specifications that allow easy implementation. |
|
However it has it's own drawbacks: |
|
- Many web servers do not support connection via UNIX domain sockets and auto start. |
- SCGI web server implementation are usually more buggy in comparison to FastCGI. |
|
It should be used if no FastCGI API is available, or libcppcms compiled without fastcgi support. |
|
[CGI](http://www.w3.org/CGI/) -- may be used only in three cases: |
|
- Web server do not support fastcgi and scgi and there is no option to use `cgi-fcgi` "connector" |
- Debugging |
- CppCMS application is heavy CPU bounded, thus the time required for fork+exec is negligible. |
|
### API Parameters |
|
- `server.socket` -- FastCGI or SCGI socket. For Unix Domain socket, specify path |
|
server.socket="/tmp/myapp.fcgi-socket" |
|
For TCP sockets specify "[IP]:port" for example |
|
server.socket="127.0.0.1:6001" |
server.socket=":6001" |
|
Default socket is Standard Input -- 0. It is used when web server starts |
FastCGI/SCGI application. |
|
- `server.buffer` -- How many requests can be "on-hold" -- actually parameters for listen(2) |
it is also used for internal buffer size of "mod-thread" |
|
server.buffer = 100 |
|
Default is 1. |
|
## CppCMS Server Mod -- `server.mod` |
|
Unless `server.api` is CGI, this parameter is mandatory. Three modes are availible: "process", "thread" and "prefork". For example |
|
server.mod = "prefork" |
|
- **`process`** -- CppCMS application runs in single thread, this is the simplest and quite safe mod. If application crashes, only one session is aborted. However, every shared data should pass through IPC -- cache, sessions etc. |
- **`thread`** -- CppCMS runs as single process, all application instances run in thread pool. This can be used for best performance. Drawbacks -- in case of crash, all CppCMS server goes down. |
|
Parameters: `server.threads` --- the size of thread pool. Default is 5 threads. |
|
- **`prefork`** -- CppCMS spawns process pool that execute queries, when "parent" process controls |
this poll. Every application run in its own process as single thread. |
|
If application crashes, missing process is automatically "reforked" by parent providing |
best degree of safety. Also, the iterations limit can be set to force processes die and |
prevent memory and resources leaks in "hard way". |
|
Parameters: |
|
- `server.iterations_limit` -- the number of interations that each process can procced before |
respawning. Default: unlimited. |
- `server.procs` -- the size of workers pool. Default: 5 worker processes. |
|
## GZip Compression |
|
Today, most of browsers accept gzip compressed pages sending header "Accept-Encoding: gzip". If |
the browser supports "gzip", the output page is automatically compressed and sent do it, saving |
server bandwith. More then that, when caching is enabled, the cached page is storred in both compressed |
and uncompressed formats. This allows send cached page much faster --- without recompressing |
their content. |
|
Gzip compression is enabled by default. To disable it (not recommended) use: |
|
gzip.enable = 0 |
|
Compression level has significant impact on the performacne of the system. Thus, if your |
application does not use cache or has high cache miss ratio, reducing compression level to |
minimal would significanly increase performance (up to twice), while the size of output would chagne in |
about 10%. |
|
gzip.level = 1 # Minimal |
|
Compression buffer size can be defined as well using `gzip.buffer`. The size in bytes. |
|
## Cache |
|
There are several backends for caching in CppCMS. They are defined by parameter `cache.backend`" |
|
1. **`threaded`** -- cache for an application that runs in single process, usually mod-thread. All |
its internal data placed in single process. |
|
Parameters: `cache.limit` -- number of entries that are stored in cache. Default 100. |
|
For example |
|
cache.backed |
|
cache.backed = "threaded" |
cache.limit = 10000 |
|
2. **`fork`** -- cache for an application that runs in mod-prefork. The data is placed in shared |
memory avalilible for forked processes. |
3. **`tcp`** -- distributed cache system. It can be used with |
memory avalilible for forked processes. |
|
Parameters: `cache.memsize` -- the size of shared |
memory region in KB. |
|
_Note:_ Entries bigger than 5% of the size are not |
stored. |
|
For example: |
|
cache.backend = "fork" |
cache.memsize = 65536 # 64 MB |
|
3. **`tcp`** -- distributed cache system. It can be used with all available working modes. It works similarly to |
[memcached](http://www.danga.com/memcached/), but provides |
more powerful feature, like dependencies tracking. |
|
Parameters: |
|
- `cache.ips` -- the list of IPs of cache servers. |
- `cache.ports` -- the list of ports of cache servers. |
|
For example: |
|
cache.backend = "tcp" |
cache.ips = { "192.168.2.101" "192.168.2.102" } |
cache.ports = { 6010 6010 } |
|
_Note_: All entries are equally distributed over all |
servers. It is important to define same order of |
of parameters for each CppCMS server running in the |
network, because each key has unique mapping to specific |
server. |
|
## Templates |
|
If your application loads templates dynamicly from shared objects, you should define, the list |
of directories where the lookup should be performed. For example: |
|
templates.dirs = { "/usr/local/lib/blog/" "/home/yossi/blog/personal" } |
templates.dirs = { "/usr/local/lib/blog/" "/opt/views" } |
|
CppCMS would look in this directories for files ending with ".so" under various UNIXes or ".dll" |
under Cygwin and try to load the templates. |
|
If on your OS uses different extension, you may specify it with: `templates.ext`. For example: |
|
templates.ext = ".dlib" |
|
## Localization |
|
CppCMS uses it's own implementation of [gettext](http://www.gnu.org/software/gettext/) that allows |
using different locales withing same process. |
|
It has following parameters |
|
- `locale.dir` -- the path to directory with dictionaries. |
|
For example if your dictionary is stored under |
`/usr/share/locale/he/LC_MESSAGES/wiki.mo` |
then you need specify: |
|
locale.dir = "/usr/share/locale" |
|
- `locale.lang_list` -- the list of supported languages. Locale "en" is the "default" -- inline code without dictionary. |
- `locale.lang_default` -- the default language. If not specified the first language in the list "lang\_list" is the default one. |
- `locale.domain_list` -- the list of supported domains. |
- `locale.domain_default` -- the default domain. If not specified, the first in `domain_list` is used. |
|
For example: |
|
locale.dir = "/usr/share/locale" |
locale.lang_list = { "en" "ru" "he" } |
locale.lang_default = "he" |
locale.domain_list = { "wiki" "wiki_views" } |
locale.domain_default = "wiki" |
|
|
