Ansible nginx-supervisor

A base Ansible role that setups and manages a webapp via supervisor, and served up on a NGINX web server. The goal of this role is to extract the common elements of deploying a webapp into this infrastructure, in a simple and sane manner. Additionally the role provides sane defaults for logging and folder structure setup.

Requirements

• aptitude or python-apt (required by apt tasks)

This role is designed to work against a modern Ubuntu system. (Tested on Ubuntu 14.04 and 16.04) It should theoretically work on older versions of Ubuntu or Debian based systems.

Example Playbook

The simplest way to include the role in your playbook is to copy the below configuration. Remember to modify the app_name, app_nginx_hostname and app_service_command parameters especially.

- hosts: servers
  sudo: yes
  roles:
      - { role: nginx-supervisor,
          nsbase_app_name: app,
          nsbase_app_nginx_hostname: app.domain.net,
          nsbase_app_service_command: app_executable --port 9000 }

The role itself is very configurable. For exaple, if you prefer the location of the web application to refer to the domain name rather than the default root path, then simply override the nsbase_app_root_path variable with something like:

nsbase_app_rooth_path: "{{ nsbase_web_root_path }}/{{ nsbase_app_nginx_hostname }}"

A comprehensive example can be found in the [Ansible rookeries role] (https://bitbucket.org/dorianpula/ansible-rookeries) that uses this role as a base to deploy a Flask-based webapp.

Role Variables

There are a few crucial variables that you need to configure for your app. They are broken up into sections and described below:

Note that all the variables have a prefix nsbase_ to avoid naming conflicts with other roles.

App Settings

• nsbase_app_name:
  • The name of app to manage via this role.
  • Used as a prefix through out the role.
• nsbase_app_root_path:
  • The path to the root folder of the app.
  • Default: nsbase_web_root_path/nsbase_app_name_webapp

NGINX

• nsbase_app_nginx_hostname:
  • The DNS hostname that the application serves.
  • Default: localhost
• nsbase_app_nginx_app_static:
  • The path to the static elements of the site (templates, CSS, images, etc.)
  • Default: nsbase_app_root_path/nsbase_app_name/static/

App Specific

• nsbase_app_service_command:
  • The full command to execute to run the application
• nsbase_app_service_stop_signal:
  • The signal used to gracefully stop the application.
  • Default: QUIT (as in SIGQUIT)

General Web

These variables are not as crucial to configure. They do give good defaults for configuring the system in a consistent, POSIX/LSB-friendly and user-friendly manner. See the section on Default File Structure for more details.

• nsbase_web_root_path:
  • The root of the entire web app structure include configuration and logging.
  • Default: /srv/www
• nsbase_web_server_group:
  • The user group responsible for starting, stopping and managing the web and app servers on the target machine.
  • Default: www-data
• nsbase_app_service_name:
  • The name of the service setup for the app according to supervisor.
  • Default: nsbase_app_name

Default File Structure

By default the role will organize files in the following directory structure:

/srv/www
├── config
│   ├── nginx -> /etc/nginx
│   └── supervisor -> /etc/supervisor
├── logs
│   ├── nginx -> /var/log/nginx
│   └── supervisor -> /var/log/supervisor
└── app_webapp
    └── app

Internal Variables

The following variables are part of the internals of the role. However if you really want to, you can tweak them to work with your setup:

• nsbase_web_user:
  • The non-root user who is allowed to control web + app servers on the target machine.
  • Default: current user
• nsbase_nginx_app_conf:
  • The filename of the NGINX configuration for the app.
  • Default: nsbase_app_name_nginx.conf
• nsbase_supervisor_app_config:
  • The filename of the supervisor configuration for the app.
  • Default: nsbase_app_name_supervisor.conf

License

BSD

Author Information

Dorian Pula

• twitter: @dorianpula
• email: dorian.pula at amber-penguin.software.ca
• www: http://amber-penguin-software.ca

This role is a spin-off of the technology developed for the [Rookeries project] (http://rookeries.org/)

Repositories

• Main: https://bitbucket.org/dorianpula/ansible-nginx-supervisor
  • All development and issues are worked on this repo.