Defining new options for your instances

Sometimes the built-in options are not enough. For example, you may need togive 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 asper-datacenter or per-server-type options. Declaring new options for yourconfig files/command-line is a good way of achieving these goals.

To define new options use —declare-option:

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

An useful example could be defining a “redirect” option, using the redirectplugin of the InternalRouting subsystem:

  1. --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 shellscripts, the backslash is required to make your shell not expand thesevalues.

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

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

Config.ini:

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

or directly on the command line:

  1. 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:

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

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

  1. [uwsgi]
  2. ; include new shortcuts
  3. ini = shortcuts.ini
  4.  
  5. ; classic options
  6. http = :8080
  7. master = true
  8. threads = 4
  9.  
  10. ; our new option
  11. trac = /var/www/trac/fooenv

A config for Web2py, in XML:

  1. <uwsgi>
  2.   <!-- import shortcuts -->
  3.   <ini>shortcuts.ini</ini>
  4.   <!-- run the https router with HIGH ciphers -->
  5.   <https>:443,test.crt,test.key,HIGH</https>
  6.  
  7.   <master/>
  8.   <processes>4</processes>
  9.  
  10.   <!-- load web2py from /var/www/we2py -->
  11.   <web2py>/var/www/we2py</web2py>
  12. </uwsgi>

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

If you manage your customers/users with the Emperor, you canconfigure 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 configuration logic magic):

[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 orconfiguration, in the server binary. Abusing this feature will enable you toembed your new option shortcuts into the server binary, automagically allowingusers to use them. To embed your shortcuts file, edit your build profile (likebuildconf/base.ini) and set embed_config to the path of theshortcuts file. Rebuild your server and your new options will be available.

See also

BuildConf