This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description
Overview
--------

ploybot is a Fabric_ based tool for setting up Python WSGI apps on what I like to
call the SNUG stack:

* Supervisord_ for starting processes and keeping them alive.
* Nginx_ for proxying between your WSGI app and the big bad web.
* Ubuntu_ as the OS of choice, enabling resolution of system dependencies with
apt. Debian might work as well but hasn't been tested.
* Gunicorn_ for serving your WSGI app.

(I suppose it could also be the GUNS stack but that sounds far less friendly.)

Key Features
~~~~~~~~~~~~

* Deploy your site to one or more servers with a single command ('ploybot push').
* Automatic configuration of Nginx, Supervisord, and Gunicorn to get your site running.
* Isolation of each site into a separate Virtualenv_
* Support for differing app config depending on which role you deploy to (a
different DB in staging than production, for example).

Installation
~~~~~~~~~~~~

Use pip::

pip install ploybot

You can also install the current development version straight from bitbucket::

pip install hg+http://bitbucket.org/dori/ploybot#egg=ploybot

Commands
--------

(Almost) all of the commands below require that you specify a role name, like
'ploybot dosomething -R dev'.

Commands can generally be run from the site root directory or any subdirectory
of it.

push
~~~~

::

ploybot push -R rolename

This command is the main reason for ploybot's existence. It does the work required
to get your app running on a host (or set of hosts) given the configuration
specified in site.yaml and the selected role .yaml file. 'push' does the
following:

1. SSHes to the remote server(s) specified in the role config.
2. Creates a zipped up rollback archive of the old site if there's one
there already.
3. Creates a virtualenv for the site.
4. Installs apt and python dependencies.
5. Copies the site from your local machine to a temporary directory on the
remote server.
6. Writes config file includes for nginx and supervisord.
7. Moves your code from the temp dir into its production location
(/srv/<sitename> by default).
8. Tells nginx and supervisord to reload their configs.


rollback
~~~~~~~~

::

ploybot rollback -R rolename

This command is for when you have those 'OMG I BROKE THE SITE' moments. It will
SSH to the push_hosts specified in your role file and restore the most recent
archive of the site. ploybot keeps 3 rollback copies of your site, so you could
potentially run 'ploybot rollback' 3 times to go back to the state from 3
deployments ago.

run
~~~

::

ploybot run -R rolename

This command runs the site from the local machine, on port 8000. (Nothing is
pushed of copied.) Static directories listed in the *static_dirs* section of
site.yaml will also be served. (CherryPy is used for this magic.)

install_server_deps
~~~~~~~~~~~~

::

ploybot install_server_deps -R rolename

When you get a shiny new server with that fresh Ubuntu smell, it needs just a
tiny bit of setup before it will know how to serve ploybot-deployed sites. This
command does that. It installs nginx and supervisord, and gives each of them a
wildcard include in their configs for loading from /srv/<sitename>/conf.

pip_deps
~~~~

::

ploybot pip_deps

This command wraps 'pip install' to install all of the python packages listed
in requirements.txt into your local python environment. It's handy for grabbing all
the dependencies when you're working with a new virtualenv on an existing
project.


create_virtualenv
~~~~

::

ploybot create_virtualenv

Creates a virtual environment for the app to be deployed.


configure_nginx
~~~~

ploybot configure_nginx

Configures nginx


switch_nginx
~~~~

ploybot switch_nginx

Reloads nginx config


configure_supervisor
~~~~

ploybot configure_supervisor

Configures supervisor


start_process
~~~~

ploybot start_process

Starts process


stop_other_versions
~~~~

ploybot stop_other_versions

Kills other running proccesses of this app


skel
~~~~

::

ploybot skel sitename

Creates a directory with a basic ploybot file and directory structure.

Layout
------

A ploybot-enabled project should be layed out something like this::

mysite.com
├── deps.yaml
├── fabfile.py
├── membrane.py
├── roles
│   ├── dev.yaml
│   ├── staging.yaml
│   └── production.yaml
├── site.yaml
└── my-django-project

Some of those files/folders are required, other are optional:

Required
~~~~~~~~

1. site.yaml - This is the main config file (comparable to app.yaml in Google
App Engine)
2. deps.yaml - Lists Python packages, Ubuntu apt packages, and apt build
dependencies that need to be installed on the server running your site.
3. fabfile.py - A Fabric_-compatible fabfile that imports ploybot's Fabric
functions.
4. roles/\*.yaml - One or more 'role' files that contain the config to be
passed into your app depending on the deployment context.

All of the required files will be created for you with the 'ploybot skel' command.

Optional
~~~~~~~~

1. membrane.py - For Django projects it's nice to have a little shim to expose
the project as a WSGI app. I like to call mine membrane.py. You can use
whatever you like, or nothing at all, depending on your setup.
2. my-django-project - ploybot isn't restricted to Django; any valid WSGI app on
your Python path should be servable. But for Django projects I think it
makes sense to stick them right there.

.. _Supervisord: http://supervisord.org/
.. _Nginx: http://nginx.org/
.. _Ubuntu: http://www.ubuntu.com/
.. _Gunicorn: http://gunicorn.org/
.. _Fabric: http://docs.fabfile.org/
.. _Virtualenv: http://virtualenv.openplans.org/
Release History

Release History

0.1

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting