Skip to content

Latest commit

 

History

History
137 lines (90 loc) · 4.17 KB

CustomOptions.rst

File metadata and controls

137 lines (90 loc) · 4.17 KB
Raw

Defining new options for your instances

Sometimes the built-in options are not enough. For example, you may need to give your customers custom options for configuring their apps on your platform. Or you need to configure so many instances you want to simplify things such as per-datacenter or per-server-type options. Declaring new options for your config files/command-line is a good way of achieving these goals.

To define new options use --declare-option:

--declare-option <option_name>=<option1=value1>[;<option2=value2>;<option3=value3>...]

An useful example could be defining a "redirect" option, using the redirect plugin of the InternalRouting subsystem:

--declare-option "redirect=route=\$1 redirect:\$2"

This will declare a new option called redirect that takes 2 arguments. Those arguments will be expanded using the $-prefixed variables. Like shell scripts, the backslash is required to make your shell not expand these values.

Now you will be able to define a redirect in your config files:

uwsgi --declare-option "redirect=route=\$1 redirect:\$2" --ini config.ini

Config.ini:

[uwsgi]
socket = :3031
; define my redirects
redirect = ^/foo http://unbit.it
redirect = \.jpg$ http://uwsgi.it/test
redirect = ^/foo/bar/ /test

or directly on the command line:

uwsgi --declare-option "redirect=route=\$1 redirect:\$2" --socket :3031 --redirect "^/foo http://unbit.it" --redirect "\.jpg$ http://uwsgi.it/test" --redirect "^/foo/bar/ /test"

More fun: a bunch of shortcuts

Now we will define new options for frequently-used apps.

Shortcuts.ini:

[uwsgi]
; let's define a shortcut for trac (new syntax: trac=<path_to_trac_instance>)
declare-option = trac=plugin=python;env=TRAC_ENV=$1;module=trac.web.main:dispach_request
; one for web2py (new syntax: web2py=<path_to_web2_py_dir>)
declare-option = web2py=plugin=python;chdir=$1;module=wsgihandler
; another for flask (new syntax: flask=<path_to_your_app_entry_point>)
declare-option = flask=plugin=python;wsgi-file=$1;callable=app

To hook up a Trac instance on /var/www/trac/fooenv:

[uwsgi]
; include new shortcuts
ini = shortcuts.ini

; classic options
http = :8080
master = true
threads = 4

; our new option
trac = /var/www/trac/fooenv

A config for Web2py, in XML:

<uwsgi>
  <!-- import shortcuts -->
  <ini>shortcuts.ini</ini>
  <!-- run the https router with HIGH ciphers -->
  <https>:443,test.crt,test.key,HIGH</https>

  <master/>
  <processes>4</processes>

  <!-- load web2py from /var/www/we2py -->
  <web2py>/var/www/we2py</web2py>
</uwsgi>

A trick for the Emperor: automatically import shortcuts for your vassals

If you manage your customers/users with the :doc:`Emperor<Emperor>`, you can configure it to automatically import your shortcuts in each vassal.

uwsgi --emperor /etc/uwsgi/vassals --vassals-include /etc/uwsgi/shortcuts.ini

For multiple shortcuts use:

uwsgi --emperor /etc/uwsgi/vassals --vassals-include /etc/uwsgi/shortcuts.ini --vassals-include /etc/uwsgi/shortcuts2.ini --vassals-include /etc/uwsgi/shortcuts3.ini

Or (with a bit of :doc:`configuration logic magic<ConfigLogic>`):

[uwsgi]
emperor = /etc/uwsgi/vassals

for = shortcuts shortcuts2 shortcuts3
  vassals-include = /etc/uwsgi/%(_).ini
endfor =

An advanced trick: embedding shortcuts in your uWSGI binary

uWSGI's build system allows you to embed files, be they generic files or configuration, in the server binary. Abusing this feature will enable you to embed your new option shortcuts to the server binary, automagically allowing users to use them. To embed your shortcuts file, edit your build profile (like :file:`buildconf/base.ini`) and set embed_config to the path of the shortcuts file. Rebuild your server and your new options will be available.

.. seealso:: :doc:`BuildConf`