Configuration file

This is the default configuration file for plugin template: node

```ini

GENERAL SECTION

(plugin metadatas)

[general]

Notes about the name of the plugin:

- the name of the plugin is given by the content of .layerapi2_label

in this directory (format: plugin_{name of the plugin}@mfserv)

- the old "name" key in this file is not used anymore

Version of the plugin (X.Y.Z)

If the value is {{MFMODULE_VERSION}},

the current module version is used

_version=0.0.1

Release of the plugin

_release=1

Summary (one line) of the goal of the plugin

_summary=one line summary

License of the plugin

_license=Proprietary

URL of the plugin homepage

_url=http://yourpluginhomepage

Name of the maintainer of the plugin on the form "Firstname FAMILYNAME "

_maintainer=Firstname FAMILYNAME

Vendor of the plugin

_vendor=Vendor

!!! ADVANCED SETTING !!!

Use this only if you are sure about what you are doing

extra nginx configuration filename inside your plugin directory

null => no extra configuration

The content will be included directly in "http" section

If you want to include some configuration fragments specific to an app

don't use this key (in [general] section] but extra_nginx_conf_filename

in [app_xxxxx] section.

Note: if you use this key, you can break the whole mfserv module

=> so there will be a warning at plugin installation about that

Note: the difference between this key and the one just below is that

the configuration fragment will be inserted in "http" section

(for this one) and in "server" section (for the one below)

_extra_nginx_http_conf_filename=null

!!! ADVANCED SETTING !!!

Use this only if you are sure about what you are doing

extra nginx configuration filename inside your plugin directory

null => no extra configuration

The content will be included directly in "server" section

If you want to include some configuration fragments specific to an app

don't use this key (in [general] section] but extra_nginx_conf_filename

in [app_xxxxx] section.

Note: this key is not used with virtualdomain_based_routing

Note: if you use this key, you can break the whole mfserv module

=> so there will be a warning at plugin installation about that

Note: the difference between this key and the one just above is that

the configuration fragment will be inserted in "server" section

(for this one) and in "http" section (for the one above)

_extra_nginx_server_conf_filename=null

!!! ADVANCED SETTING !!!

Use this only if you are sure about what you are doing

extra nginx configuration filename inside your plugin directory

null => no extra configuration

The content will be included directly in "init_worker_by_lua_block" section

and must be valid LUA code!

Note: if you use this key, you can break the whole mfserv module

=> so there will be a warning at plugin installation about that

_extra_nginx_init_worker_by_lua_block_filename=null

if set to false, don't add the plugin directory in "lua packages path"

(so you have to require your lua files with require("{your plugin name}.{your lua file}")

don't change this unless you know exactly what you are doing

(if you set to false, you can introduce some path collisions when using multiple

openresty plugins even it was the default with mfserv <= 1.0.4)

_add_plugin_dir_to_lua_path=false

APP SECTION

(Note: with this plugin type, you can't have several section like this one)

[app_main]

Command to be executed

Notes:

- null means no command to execute

- this command can be launched several times (see workers/numprocesses)

- the command must listen to {unix_socket_path} (dynamically generated)

- the launched command must run foreground and listen for http requests on

{unix_socket_path} unix socket

- you can use following placeholders:

- {unix_socket_path} (full path for a unique dynamically generated unix

socket for the worker)

- {timeout} (timout in seconds for dealing with 1 request)

- {plugin_name} (plugin name)

- {plugin_dir} (plugin directory full path)

- {app_name} (app name without app_ prefix)

- {debug_extra_options} (the content of debug_extra_options only if debug=1

or empty if debug=0)

_cmd_and_args=node {debug_extra_options} "{plugin_dir}/{plugin_name}/server.js" "{unix_socket_path}" {timeout}

For mfserv plugins that process web requests by gateway interface,

specify its mode to set up nginx correctly

Values can be proxy (-> proxy_pass) or fastcgi (-> fastcgi_pass)

_gateway_interface_mode=proxy

Very advanced options, change this only if you exactly know what you are doing

The previous command is wrapped into a signal_wrapper.py app.

When we want to do a "really smart" restart, the stop signal is catched by

signal_wrapper which:

(1) order to nginx to stop to route new requests to this process

(2) wait until there is no connection active to the process anymore

(the timeout of this way is given by the {timeout} key)

(3) send {smart_stop_signal} to the configured command ({cmd_and_args})

(4) wait until {smart_stop_delay} seconds for the configured command to exit

(if we exceed the delay, a SIGKILL is sent)

(5) exit itself

Then a new process is launched (by circus) and then we wait

{smart_start_delay} seconds before saying to nginx:

"ok you can route new http requests to the new process"

smart_stop_signal=15 smart_stop_delay=3 smart_start_delay=3

number of workers / processes

note: you can use {{MFHARDWARE_NUMBER_OF_CPU_CORES_MULTIPLIED_BY_2}} value

to avoid a kind of hardware automatic value (see "env |grep HARDWARE" as

mfserv to find other automatic values)

numprocesses={{MFHARDWARE_NUMBER_OF_CPU_CORES_MULTIPLIED_BY_2}}

timeout (in seconds) for one request

(if null or <=0, the MFSERV_NGINX_TIMEOUT is used)

timeout=0

If you set debug=1, numprocesses will be forced to 1 and we will try

to set all debug options and features (max_age will also be forced

to 0 and mflog minimal level will be set to DEBUG)

DON'T USE IT ON PRODUCTION!!!

debug=0

Options to inject if previous key "debug" it set to 1

(the placeholder {debug_extra_options} must be used in cmd_and_args key)

Note: if debug=0, then {debug_extra_options} placeholder is empty even if

the following key contains something)

_debug_extra_options=debug

Use prefix based routing:

http://{host}:{port}/{plugin_name}/{app_name}/...

(and/or)

http://{host}:{port}/{plugin_name}/...

if app_name == main or only one app in the plugin

_prefix_based_routing=true

Use virtualdomain based routing

http://{app_name}.{plugin_name}.{host}:{port}/...

(and/or)

http://{plugin_name}.{host}:{port}/...

if app_name == main or only one app in the plugin

NOTE: you need a DNS "catch all" to do that (like a DNS CNAME

*.{host} => {ip_of_the_host})

_virtualdomain_based_routing=false

Route directly at the webserver part some /static url part to a

/static directory inside the application directory (static files hosting)

(you can configure this feature with static_url_prefix and

static_directory key)

_static_routing=true

If static_routing=true, url prefix for static to route static files

Notes :

- with prefix_based_routing, this is relative to app url prefix

- the value should start with '/' and must not end with '/'

_static_url_prefix=/static

If static_routing=true, directory prefix for static files

Notes :

- this is relative to app directory

- the value should not start with '/' and must not end with '/'

_static_directory=/static

!!! ADVANCED SETTING !!!

Add extra routes to your plugin (starting by /, not ending by /,

separated by ;)

Example: prefix_based_routing_extra_routes=/foo;/bar

null => no extra routes

/ => all routes

Note: if you use this key, you can break the whole mfserv module

and generate some conflicts with other plugins

=> so there will be a warning at plugin installation about that

prefix_based_routing_extra_routes=null

If _virtualdomain_based_routing is true, this parameter

can be used to add some extra vhosts for this plugin

(coma separated list of extra vhosts)

(null or empty means no extra domains)

virtualdomain_based_routing_extra_vhosts=null

!!! ADVANCED SETTING !!!

Use this only if you are sure about what you are doing

extra nginx configuration filename inside your plugin directory

null => no extra configuration

The content will be included directly in your app "location" section

If you want to include some configuration fragments at a more general level

don't use this key but those in the [general] section

Note: if you use virtualdomain_based_routing, the content will be included

in the custom "location" / of "server" section (specific to your app)

_extra_nginx_conf_filename=null

!!! ADVANCED SETTING !!!

Use this only if you are sure about what you are doing

extra nginx configuration filename inside your plugin directory

null => no extra configuration

The content will be included directly in your app "location" section for

the "static" routing part (see also extra_nginx_conf_filename key for

the "dynamic" part)

If you want to include some configuration fragments at a more general level

don't use this key but the one in [general] section)

_extra_nginx_conf_static_filename=null

Optional http point to diagnose plugin health during mfserv.status

null => this feature is not activated

else a GET request will be done on

http://127.0.0.1:{MFSERV_NGINX_PORT}{YOUR_ENDPOINT}

(so http_test_endpoint must start with a slash)

If the result status code is {http_test_expected_status_code} and if the

{http_test_expected_body} is found in the result body, then the test is ok

If not, we will retry until {http_test_timeout} timeout (in seconds)

After this timeout, the test will fail

Note: if you want something more specific that this basic test, you can

implement a plugin.status executable in your plugin bin/ subdirectory

it will be called (with a 30s timeout) and it will pass if the

return code is 0

_http_test_endpoint=null _http_test_expected_status_code=200 _http_test_expected_body=OK _http_test_timeout=10

resource limit for each app worker

rlimit_as => maximum area (in bytes) of address space which may be taken

by the worker.

rlimit_nofile => maximum number of open file descriptors for the current

worker.

rlimit_stack => maximum size (in bytes) of the call stack for the current

worker. This only affects the stack of the main thread

in a multi-threaded worker.

rlimit_fsize => maximum size of a file which the worker may create.

(empty value means no limit)

rlimit_as = 1000000000 rlimit_nofile = 1000 rlimit_stack = 10000000 rlimit_fsize = 100000000

If set then the process will be restarted sometime after max_age and

max_age + random(0, max_age) seconds.

0 => disable this feature

Note: the feature is automatically disabled if workers=1

Note: 60 is probably a minimum

Note: if you use this feature, have also a look at smart_stop_ and smart_start_ parameters

max_age = 0

Split stdout/stderr logs into different files?

AUTO => the global conf MFSERV_LOG_TRY_TO_SPLIT_STDOUT_STDERR is used

(default: don't split)

1 => split

0 => don't split

log_split_stdout_stderr=AUTO

Split logs of multiple workers into different log files?

AUTO => the global conf MFSERV_LOG_TRY_TO_SPLIT_MULTIPLE_WORKERS is used

(default: don't split)

1 => split

0 => don't split

log_split_multiple_workers=AUTO

!!! ADVANCED SETTINGS !!!

You can add extra daemons which will be launched within your plugin

by providing configuration blocks [extra_daemon_*]

You have to provide a command to daemonize (the command must run in

foreground and not daemonize by itself)

[extra_daemon_foo]

_cmd_and_args = /your/foreground/command command_arg1 command_arg2

numprocesses=1

graceful_timeout = 30

rlimit_as = 1000000000

rlimit_nofile = 1000

rlimit_stack = 10000000

rlimit_fsize = 100000000

log_split_stdout_stderr=AUTO

log_split_multiple_workers=AUTO

max_age=0

[custom]

Here is a space for your public configuration keys

(ie. overridable by administrator after deployment)

Your keys shouldn't start with an underscore (as they are public)

and you have to read their value through the corresponding env variable

and NOT by parsing this file

A key named "foo_bar" here will generate (in plugin_env) an env var called

MFSERV_CURRENT_PLUGIN_CUSTOM_FOO_BAR

(MFSERV_CURRENT_PLUGIN_CUSTOM_{YOUR KEY IN UPPERCASE})

with the corresponding value inside

```