web Package

web Package

Roles in this namespace are meant to configure either Web Servers (apache, nginx) or Web App Servers (tornado, django, rails) in Debian distributions.

apache Module

Roles in this namespace are meant to provide Apache HTTP Server utility methods for Debian distributions.

class provy.more.debian.web.apache.ApacheRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides Apache HTTP Server management utilities for Debian distributions.

Provisions with apache2 as default, that is, it uses the apache2-mpm-worker variant.

If you want to use the apache2-mpm-prefork variant, just use install this package with AptitudeRole and restart Apache.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.ensure_mod('php5') # Installs and enables mod_php
            role.ensure_site_disabled('default')
            role.create_site(site='my-site', template='my-site')
            role.ensure_site_enabled('my-site')
cleanup()[source]

Restarts Apache if any changes have been made.

There’s no need to call this method manually.

create_site(site, template, options={})[source]

Adds a website with the specified template to Apache list of available sites.

Warning

Do not forget to call ensure_site_enabled() after a call to create_site, or your site won’t be enabled.

Parameters:
  • site (str) – Name of the site to enable.
  • template (str) – Site configuration template.
  • options (dict) – Options to pass to the template. Defaults to empty dict ({}).

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.create_site(site='my-site', template='my-site', options={
                "foo": "bar"
            })
ensure_mod(mod)[source]

Installs the module package and enables it in Apache.

Parameters:mod (str) – Name of the module to enable.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.ensure_mod('php5') # Installs "libapache2-mod-php5" and enables it
ensure_restart()[source]

Ensures that Apache gets restarted on cleanup. There’s no need to call this method as any changes to Apache will trigger it.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.ensure_restart()
ensure_site_disabled(site)[source]

Ensures that the specified site is removed from the Apache list of enabled sites.

Parameters:site (str) – Name of the site to disable.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.ensure_site_disabled('default')
ensure_site_enabled(site)[source]

Ensures that a symlink is created for the specified site at the Apache list of enabled sites from the list of available sites.

Parameters:site (str) – Name of the site to enable.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.ensure_site_enabled('my-site')
provision()[source]

Installs Apache dependencies. This method should be called upon if overriden in base classes, or Apache won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(ApacheRole) # does not need to be called if using with block.
restart()[source]

Forcefully restarts Apache.

Example:

from provy.core import Role
from provy.more.debian import ApacheRole

class MySampleRole(Role):
    def provision(self):
        with self.using(ApacheRole) as role:
            role.restart()

django Module

Roles in this namespace are meant to provide Django app server utility methods for Debian distributions.

class provy.more.debian.web.django.DjangoRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides Django management utilities for Debian distributions.

When running Django under supervisor, remember to set restart_supervisor_on_changes() to True.

If you choose to automatically include supervisor support in your sites, don’t forget to call SupervisorRole.config method.

When creating a new site using with role.create_site(‘somesite’) as site these are the properties available in the site object:

Variables:
  • auto_start – (bool) Indicates whether the site should be automatically started by the operating system. Defaults to True. If using supervisor, explicitly set this to False.
  • daemon – (bool) Indicates whether the init.d command for the website should daemonize itself. Defaults to True. If using supervisor, explicitly set this to False.
  • settings_path – (str) This is the only mandatory argument. This is the full path to Django’s settings.py file.
  • host – (str) The host IP address that django will listen to incoming requests. Defaults to 0.0.0.0.
  • starting_port – (int) The first port that Django will be started in the event that more than one process is used. Defaults to 8000.
  • processes – (int) The number of processes that will have commands created at the server. As an example, if this is set to 2 and the name of the site is ‘website’, two commands will be created: /etc/init.d/website-8000 and /etc/init.d/website-8001. Defaults to 1.
  • pid_file_path – (str) Path to create the pid file. Defaults to /var/run.
  • threads – (int) Number of worker threads that Green Unicorn will use when spawning Django. Defaults to 1.
  • user – (str) User that gunicorn will run under. Defaults to the last created user. When using supervisor it is VERY important that this user is the same user as supervisor’s.
  • use_supervisor – (bool) Whether supervisor configuration for these django website should be automatically included.
  • supervisor_log_folder – (str) Log folder that supervisor will store the configurations for this site.
  • settings – (dict) Dictionary with settings that will overwrite Django’s defaults. These settings will be included in a local_settings.py module that imports the original settings as KEY=value pairs. All values included here will have their string representation used in the local_settings.

Example:

from provy.core import Role
from provy.more.debian import DjangoRole

class MySampleRole(Role):
    def provision(self):
        with self.using(SupervisorRole) as role:
            role.config(
                config_file_directory='/home/someuser',
                log_file='/home/someuser/logs/supervisord.log',
                user='myuser'
            )

        with self.using(DjangoRole) as role:
            role.restart_supervisor_on_changes = True
            with role.create_site('mysite') as site:
                site.path = '/some/folder/with/settings.py'
                site.use_supervisor = True
                site.supervisor_log_path = '/some/folder/to/log'
                site.threads = 4
                site.processes = 2
                site.user = 'myuser'
                # settings that override the website defaults.
                site.settings = {

                }
cleanup()[source]

Updates the website and/or init files and restarts websites if needed.

There’s no need to call this method since provy’s lifecycle will make sure it is called.

create_site(name)[source]

Enters a with block with a Site variable that allows you to configure a django website.

Parameters:name (str) – Name of the website.

Example:

from provy.core import Role
from provy.more.debian import DjangoRole

class MySampleRole(Role):
    def provision(self):
        with self.using(DjangoRole) as role:
            with role.create_site('website') as site:
                site.path = '/some/folder/with/settings.py'
                site.threads = 4
                # settings that override the website defaults.
                site.settings = {

                }
provision()[source]

Installs Django and its dependencies. This method should be called upon if overriden in base classes, or Django won’t work properly in the remote server.

If you set a value to django-version in the context, that version of Django will be installed instead of latest.

Example:

from provy.core import Role
from provy.more.debian import DjangoRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(DjangoRole) # no need to call this if using with block.

# or
class MySampleRole(Role):
    def provision(self):
        self.context['django-version'] = '1.1.1'
        self.provision_role(DjangoRole) # no need to call this if using with block.
        # now django 1.1.1 is installed.
class provy.more.debian.web.django.WithSite(django, name)[source]

Bases: object

nginx Module

Roles in this namespace are meant to provide Nginx web server utility methods for Debian distributions.

class provy.more.debian.web.nginx.NginxRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides Nginx web server management utilities for Debian distributions.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.ensure_conf(conf_template='nginx.conf')
            role.ensure_site_disabled('default')
            role.create_site(site='my-site', template='my-site')
            role.ensure_site_enabled('my-site')
cleanup()[source]

Restarts nginx if any changes have been made. There’s no need to call this method manually.

create_site(site, template, options={})[source]

Adds a website with the specified template to Nginx list of available sites.

Warning: Do not forget to call ensure_site_enabled() after a call to create_site, or your site won’t be enabled.

Parameters:
  • site (str) – Name of the site to enable.
  • template (str) – Site configuration template.
  • options (str) – Options to pass to the template.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.create_site(site='my-site', template='my-site', options={
                "user": "me"
            })
ensure_conf(conf_template, options={}, nginx_conf_path='/etc/nginx/nginx.conf')[source]

Ensures that nginx configuration is up-to-date with the specified template.

Parameters:
  • conf_template (str) – Name of the template for nginx.conf.
  • options (dict) – Dictionary of options passed to template. Extends context.
  • nginx_conf_path (str) – Path of the nginx configuration file. Defaults to /etc/nginx/nginx.conf.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.ensure_conf(conf_template='nginx.conf')
ensure_restart()[source]

Ensures that nginx gets restarted on cleanup. There’s no need to call this method as any changes to Nginx will trigger it.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.ensure_restart()
ensure_site_disabled(site)[source]

Ensures that the specified site is removed from nginx list of enabled sites.

Parameters:site (str) – Name of the site to disable.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.ensure_site_disabled('default')
ensure_site_enabled(site)[source]

Ensures that a symlink is created for the specified site at nginx list of enabled sites from the list of available sites.

Parameters:site (str) – Name of the site to enable.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.ensure_site_enabled('my-site')
provision()[source]

Installs Nginx dependencies. This method should be called upon if overriden in base classes, or Nginx won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(NginxRole) # does not need to be called if using with block.
restart()[source]

Forcefully restarts Nginx.

Example:

from provy.core import Role
from provy.more.debian import NginxRole

class MySampleRole(Role):
    def provision(self):
        with self.using(NginxRole) as role:
            role.restart()

rails Module

Roles in this namespace are meant to provide Ruby on Rails applications utility methods for Debian distributions.

class provy.more.debian.web.rails.RailsRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides Ruby on Rails application utilities for Debian distributions.

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        with self.using(RailsRole) as role:
            role.ensure_site_disabled('default')
            role.create_site(site='my-site', path='/home/myuser/my-site')
            role.ensure_site_enabled('my-site')
cleanup()[source]

Restarts nginx if any changes have been made.

There’s no need to call this method manually.

create_site(site, host, path, port=80, options={})[source]

Adds a website with the specified template to Nginx list of available sites.

Warning

Do not forget to call ensure_site_enabled() after a call to create_site, or your site won’t be enabled.

Parameters:
  • site (str) – Name of the site to enable.
  • host (str) – Server domain that Nginx should respond by.
  • path (str) – Path of the rails app.
  • port (int) – Port that Nginx will listen in. Defaults to 80.
  • options (int) – Options to pass to the Nginx template. Defaults to empty dict ({}).

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        with self.using(RailsRole) as role:
            role.create_site(site='my-site', host='localhost www.mysite.com',
                             port=8888, path='/home/myuser/my-rails-site')
ensure_restart()[source]

Ensures that Nginx gets restarted on cleanup. There’s no need to call this method as any changes to Nginx will trigger it.

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        with self.using(RailsRole) as role:
            role.ensure_restart()
ensure_site_disabled(site)[source]

Ensures that the specified site is removed from Nginx list of enabled sites.

Parameters:site (str) – Name of the site to disable.

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        with self.using(RailsRole) as role:
            role.ensure_site_disabled('default')
ensure_site_enabled(site)[source]

Ensures that a symlink is created for the specified site at Nginx list of enabled sites from the list of available sites.

Parameters:site (str) – Name of the site to enable.

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        with self.using(RailsRole) as role:
            role.ensure_site_enabled('my-site')
provision()[source]

Installs Ruby on Rails dependencies. This method should be called upon if overriden in base classes, or Rails won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(RailsRole) # does not need to be called if using with block.
restart()[source]

Forcefully restarts nginx.

Example:

from provy.core import Role
from provy.more.debian import RailsRole

class MySampleRole(Role):
    def provision(self):
        with self.using(RailsRole) as role:
            role.restart()

tornado Module

Roles in this namespace are meant to provide Tornado app server utility methods for Debian distributions.

class provy.more.debian.web.tornado.TornadoRole(prov, context)[source]

Bases: provy.core.roles.Role

This role provides Tornado app server management utilities for Debian distributions.

Example:

from provy.core import Role
from provy.more.debian import TornadoRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(TornadoRole)
provision()[source]

Installs Tornado and its dependencies. This method should be called upon if overriden in base classes, or Tornado won’t work properly in the remote server.

Example:

from provy.core import Role
from provy.more.debian import TornadoRole

class MySampleRole(Role):
    def provision(self):
        self.provision_role(TornadoRole)