puppet-uwsgi

A puppet module for installing and managing uWSGI (in emperor mode)

WARNING: version 2.0 and newer of this module requires Puppet 4.7 and newer. See version 1.3.2 for compatibility with Puppet 3.

This module has its roots in the work of @rvdh and @jarshwah:

• https://github.com/rvdh/puppet-uwsgi - (Forge Module)
• https://github.com/jarshwah/puppet-uwsgi - (Forge Module)

Description

This module installs and configures uWSGI in Emperor mode.

It can also create and manage uWSGI applications that run under the emperor, which are best defined in Hiera.

Just about every option is configurable, so it should work on most distributions by putting together a Hiera file.

Usage

There are two options to get uWSGI going on your machine: either include uwsgi and provide vassal configurations via uwsgi::app from Hiera or create resources via the defined type uwsgi::app by yourself (will include uwsgi for you).

If you are using this module on RedHat like distributions, be aware the the uWSGI or Python pip package is not contained in standard repos. By default, this module will include ::epel from stahnma/epel for management (see parameters below). Remember to include this in your Puppetfile if necessary!

Option 1: include uwsgi

1. Add include uwsgi to your role or profile class.
2. Add configuration to Hiera (minimal example given):

---
uwsgi::app:
  example:
    uid: example
    gid: example

Configure multiple applications (merged with 'deep' strategy):

# common.yaml
---
uwsgi::app:
  django_1:
    ensure: 'present'
    uid: 'django'
    gid: 'django'
    application_options:
      chdir: '/path/to/project'
      module: 'mysite.wsgi:application'
      socket: '/tmp/uwsgi_django.sock'


# role_app_server.yaml
---
uwsgi::app:
  django_2:
    ensure: 'present'
    uid: 'django'
    gid: 'django'
    application_options:
      chdir: '/path/to/project2'
      module: 'mysite.wsgi:application'
      socket: '/tmp/uwsgi_django2.sock'

Option 2: create uwsgi::app resources

1. Add configuration to Hiera (minimal example given):

---
apps:
  example:
    uid: example
    gid: example

2. Create resources (minimal example):

$apps = lookup('apps')
each($app) |$name, $options| {
  uwsgi::app { $name:
    * => $options,
  }
}

Limitations

1. Users for your vassals are NOT managed by this module.
2. This module uses unit testing and acceptance testing for the supported operating system versions. Try your luck on other platforms...
3. This module does not support Puppet 3 or Puppet < 4.7 and heavily relies on Hiera 5 data-in-modules. Please upgrade.
4. Installation of uWSGI
   • Except on Ubuntu 14.04 and Debian 7, uWSGI will be installed from package repos. This enables you to install more options for uWSGI like special loggers or language support. By default, this module will imitate the pip provider behaviour and install Python support.
   • When you use the pip provider, be aware that your uWSGI installation will only support Python. You can try to use the gem provider for Ruby / Rack support, but this is neither tested nor supported. There is no support for installing more modules via uwsgiconfig.py. (Happy to accept a PR lifting these limits...!)

Defined Types

uwsgi::app

Responsible for creating uWSGI applications (vassals) that run under the uWSGI emperor.

Parameters

• uid The user to run the application as. Required. May be the user name or the id.

• gid The group to run the application as. Required. May be the group name or the id.

• ensure Ensure the config file exists. Default: 'present'

• template The template used to construct the config file. Default: 'uwsgi/uwsgi_app.ini.erb'

• application_options Hash of extra options to set in the application config file. Default: {} Example: { 'socket' => '/tmp/app.socket' }

• environment_variables Hash of extra environment variabls to set in the application config file. Default: {} Example: { 'DJANGO_ENV_VAR' => 'example' }

Using Hiera

Configure a Django application:

---
uwsgi::app:
  django:
    ensure: 'present'
    uid: 'django'
    gid: 'django'
    application_options:
      chdir: '/path/to/project'
      module: 'mysite.wsgi:application'
      socket: '/tmp/uwsgi_django.sock'
      master: 'True'
      vaccum: 'True'
      max-requests: '5000'
      buffer-size: '32768'
      processes: 4
      threads: 8

Classes

uwsgi

The main entry point. Simply include uwsgi to accept all the default parameters. The service file template will, by default, auto-configure itself depending on the service provider (RedHat init.d / UpStart / SystemD).

Parameters

• app A hash of uwsgi::app resources to create for you. See above. Default: {} Merge behaviour: deep
• plugins An array of package names to install when not using pip to install. By default this will install Python support for uWSGI. Default: depends on OS Merge behaviour: unique

Private subclasses

Any subclasses of ::uwsgi are private and normally you should not need to fiddle around with them. Instead, use parameters configurable via Hiera (see next section).

Parameters (via Hiera)

None of the following parameters are required. Depending on your distribution and version, this provides sane defaults.

If you want to add a new distribution or version, have a look at the data directory of this module.

Most certainly you want to configure some emperor options. Example:

---
uwsgi::emperor_options:
  vacuum: 'True'
  reload-mercy: 8

Installation

• uwsgi::install::package_name The package name to install.
• uwsgi::install::package_ensure Package state. Cascades to config files.
• uwsgi::install::package_provider The provider to use to install the package.
• uwsgi::install::plugins Array of plugin package names, loads from uwsgi::plugins by default.

Build and Runtime dependencies

• uwsgi::packages::manage_epel Choose to depend on epel module. Default on RedHat.
• uwsgi::packages::install_pip Install pip if it's not already installed? Don't by default.
• uwsgi::packages::install_python_dev Install python header files and other build time dependencies if not already installed? Don't by default. Merge strategy "unique".
• uwsgi::packages::python_dev String or Array of build time dependency package names.
• uwsgi::packages::python_pip String of pip package name.

Emperor Configuration

• uwsgi::config::configfile Absolute path to config file.
• uwsgi::config::log_rotate Install logrotate rule? Don't by default.
• uwsgi::config::app_directory Absolute path to store vassal configurations.
• uwsgi::config::pidfile Absolute path to pid file.
• uwsgi::config::socket Absolute path to socket file.
• uwsgi::config::emperor_options Hash of extra options for emperor ini file.
• uwsgi::config::tyrant Start emperor in "tryant" mode?
• uwsgi::config::logfile Absolute path to log file.

Service

• uwsgi::service::manage_file Provide a init system dependent start script/file? (or use package provided)
• uwsgi::service::provider Service provider of this system. Depends on your distribution.
• uwsgi::service::file Absolute path to script file.
• uwsgi::service::file_mode Mode of script file.
• uwsgi::service::template Template to use (auto depends on service provider).
• uwsgi::service::ensure Service status to ensure. Defaults to running.
• uwsgi::service::enable Start service at boot? Default to true.
• uwsgi::service::binary_directory Aboslute path to uwsgi binary.
• uwsgi::service::kill_signal Systemd specific: signal to use for termination of uWSGI.

Contributers

Contributions will be gratefully accepted. Please go to the project page, fork the project, make your changes locally and then raise a pull request. Details on how to do this are available at https://guides.github.com/activities/contributing-to-open-source.

Additional Contributers

2.0.1 - 2017-09-26

• Add credits for ancestor modules.

2.0.0 - 2017-09-14

• Breaking changes, no Puppet 3 support anymore
• Breaking changes, new class layout and defaults
• Major refactoring to "future proof" the module.

1.3.0 - 2015-04-?

• Made tyrant mode configurable
• Optionally deploy logrotate configuration

1.2.0 - 2014-08-20

• support for passing an array of values into app::application_options (Thanks @rayl)

1.1.0 - 2014-07-17

• Support for listing environment variables per application (Thanks @kimor79)
• Fix typo in the upstart script (Thanks @Kodapa)

1.0.1 - 2014-06-20

• emperor log directory can now be changed

1.0.0 - 2014-06-19

• Added init.d service template
• Auto-configure template based on service provider

0.9.0 - 2014-05-24

• Added support for uwsgi vassal creation