README.md

Ansible Role: flask-uwsgi-nginx

This Ansible role deploys your Flask application using a git repository.

The role packages your Flask app as a wheel file and installs it in a virtual environment.

Requirements

• .python-version file

  This file should specify the version of Python you want to use.

• python setup.py bdist_wheel

  The role will run this command, so test your project first to ensure it can create a wheel file.

Role Variables

• app_repo_url: 'https://github.com/lex00/flask-github-jobs'

  • The URL of your Flask application repository.

• app_subfolder: ''

  • Specify if your project is in a subfolder within the repository; otherwise, leave it blank.

• app_description: 'A Flask that lists jobs from the github jobs API'

  • This description will be used in the system service script.

• app_name: 'flask_github_jobs'

  • Name for your app folders and service.

• app_user: 'flask_github_jobs'

  • This value will be used for both the system user and group.

• app_domain: 'notarealdomain.com'

  • The domain for which nginx will serve responses.

• app_module: 'flask_github_jobs'

  • Python module name for uwsgi.ini.

• app_callable: 'app'

  • The callable in your Python code for uwsgi.ini.

• app_port: '80'

  • Port for the service.

• app_health_ep: '/'

  • Health check endpoint.

• uwsgi_process_count: '4'

  • Number of uwsgi processes to run.

• uwsgi_thread_count: '2'

  • Number of uwsgi threads to use.

Dependencies

None.

Example Playbook

- hosts: all
  tasks:
    - import_role:
        name: lex00.flask-uwsgi-nginx

Python Configuration

You can use any version of Python:

• .python-version file

  • Your project must include this file.

• /home/{{ app_user }}/.pyenv/versions

  • This is where pyenv installs Python versions.

• /opt/{{ app_name }}/venv

  • Your application will be installed in this virtual environment.

Uwsgi Configuration

Uwsgi will be installed within the virtual environment; no system packages for uwsgi will be installed.

• /etc/{{ app_name }}/app_name.ini

  • Uwsgi configuration file.

• /var/run/{{ app_name }}/{{ app_name }}.sock

  • Uwsgi socket file.

Flask Static Assets

This role will automatically find your static asset folders and set them up in nginx.

To make this work:

• Place your static files in a folder named static in your Flask app.

• Set static_url_path to an empty string:

  app = Flask(__name__, static_url_path='')
  

Service Management

For Ubuntu 14.04, to start/stop the Uwsgi service:

sudo start {{ app_name }}

For Ubuntu 14.04, to start/stop Nginx:

sudo start nginx

For Ubuntu 16 and later, to start/stop the Uwsgi service:

sudo systemctl start {{ app_name }}

For Ubuntu 16 and later, to start/stop Nginx:

sudo systemctl start nginx

Logs

Logs will be located in /var/log/{{ app_name }} and will be owned by {{ app_user }}.

Vagrant + Galaxy Example

Create a requirements.yml file with the following contents:

---
- src: lex00.flask-uwsgi-nginx

The provisioner needs the galaxy_role_file set to this:

config.vm.provision "ansible", type: "ansible_local" do |ansible|
  ansible.verbose = true
  ansible.become = true
  ansible.extra_vars = "vars.json"
  ansible.config_file = "ansible.cfg"
  ansible.galaxy_roles_path = "roles"
  ansible.galaxy_role_file = "requirements.yml"
  ansible.playbook = "playbook.yml"
end

Packer + Galaxy Example

Create a requirements.yml file with the same contents:

---
- src: lex00.flask-uwsgi-nginx

The provisioner needs the galaxy_file set to this:

{
  "type": "ansible-local",
  "host_vars": "{{ user `vars_path` }}",
  "playbook_dir": "{{ user `ansible_path` }}",
  "playbook_paths": "{{ user `ansible_path` }}",
  "role_paths": "{{ user `ansible_path` }}/roles",
  "playbook_file": "{{ user `ansible_path` }}/playbook.yml",
  "galaxy_file": "{{ user `ansible_path` }}/requirements.yml",
  "extra_arguments": [ "--extra-vars \"@host_vars/vars.json\"" ]
}

Testing with Vagrant

A Vagrantfile is included to test the role locally.

You need Vagrant version 2.0 or higher.

Start Vagrant

The first time you run this, it will execute Ansible.

flask-uwsgi-nginx$ vagrant up

The Vagrant setup should complete without errors.

Reprovision Vagrant

You can run the role again by executing:

flask-uwsgi-nginx/tests $ vagrant provision

License

MIT