Forge Home

psgi

Puppet module to create service files for PSGI (Perl Web Server Gateway Interface) apps

8,050 downloads

1,825 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.1.1 (latest)
  • 1.1.0
  • 1.0.1
  • 1.0.0
released Aug 31st 2020
This version is compatible with:
  • Puppet Enterprise 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.0.0

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'qtechnologies-psgi', '1.1.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add qtechnologies-psgi
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install qtechnologies-psgi --version 1.1.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

qtechnologies/psgi — version 1.1.1 Aug 31st 2020

puppet-psgi

Puppet module to create service files for PSGI (Perl Web Server Gateway Interface) apps.

This module sets up a systemd service file for each application passed to it.

It has been designed to fit in nicely with our NGINX module: qtechnologies/nginx. If this Nginx module is installed, this module grabs some parameters from it - things are less likely to break if there's only one source of data - especially for the shared sockets locations.

Please note the following items:
  • This module does not deploy Perl or the PSGI applications themselves - just the service file to make sure the app starts at boot and providing an easy and consistent way to start and stop it.
  • The default settings assume an OS provided Perl with some extra modules installed into a local library. However, any Perl installation can be used, you just need to configure the correct binary (usually path to plackup) and perl5lib in your hiera data.
  • If you define a website as PSGI, then change it to something else later (e.g. PHP), the service file will be left orphaned unless you have otherwise decided to manage /etc/systemd/system fully with Puppet.
  • Currently only tested on SUSE, but other platforms should work with the right hiera data.
  • Also, only tested on Dancer2 PSGI applications, but, again, other deployment types should work with the right hiera data.

Instructions

Global Settings

The following is the module internal hiera data - feeding the module parameters. These defaults can be overridden, if required:

psgi::service_dir: /etc/systemd/system
psgi::binary: /usr/bin/plackup
psgi::server: Starman
psgi::app_environment: production
psgi::perl5lib: /usr/local/perl/lib/perl5
psgi::app_lib: lib
psgi::app_script: bin/app.pl
psgi::umask: '0077'
psgi::user: 'root'
psgi::group: 'root'

The following parameters default to Nginx settings, but can be overridden by your hiera data:

  String $socket_dir = $nginx::socket_dir,
  String $web_root_parent = $nginx::web_root_parent,

e.g.:

psgi::socket_dir: /var/sockets
psgi::web_root_parent: /websites

See below for a description of the parameters.

Creating a PSGI systemd Service

Simply use the psgi::service resource, like this:

psgi::service { 'www.example.com': 
  binary => '/usr/bin/plackup',
  server => 'Twiggy',
}

You can also use create_resources if you have a hash of config items in hiera:

create_resources( psgi::service, { $web_server_name => $config['psgi'] }, {} )

Also, see our nginx module for how to call it through the nginx hiera definitions.

This will create a systemd service for the specific web server name based on the module's internal template.

It takes the following paramters:

  • web_server_name - web server name name to use (i.e. the domain name you are serving on), otherwise use the resource name
  • socket_dir - specify a different socket directory, just for this web server name - overriding what's specified in Nginx
  • app_environment - specify a different application deployment environment - defaults to production
  • binary - the full path to the PSGI binary (plackup)
  • server - the PSGI server to use - defaults to Starman
  • workers - the number of workers to start - defaults to 2
  • enabled - whether the service should be set to running always and enabled on boot. Defaults to true for production and not controlled otherwise.
  • web_root - specify a different web root, just for this web server name - overriding the default which is the concatenation of $web_root_parent and web_server_name
  • perl5lib - any additional library path to search for Perl modules
  • app_script - path to the main PSGI application script, relative to the web_root. Defaults to bin/app.pl.
  • app_lib - path to the PSGI application libraries, relative to the web_root. Defaults to lib.
  • umask - umask to use when running the PSGI application. Important for the socket creation. Defaults to 000.
  • user - the user to run the PSGI application as. Defaults to root.
  • group - the group to run the PSGI application as. Defaults to root.

Issues

This module is using hiera data that is embedded in the module rather than using a params class. This may not play nicely with other modules using the same technique unless you are using hiera 3.0.6 and above (PE 2015.3.2+).

It has only been tested on SUSE systems, using SUSE paths - patches for other platforms are welcome - we just need to create internal hiera data for the OS family.