From 1af4792a61b945aa978fa84af1e072a78ff26c35 Mon Sep 17 00:00:00 2001 From: Dorian Pula Date: Wed, 21 Jan 2015 09:05:19 -0500 Subject: [PATCH] Add remaining documentation to the README. Also update role with more consistent variable names. --- README.md | 105 ++++++++++++++++------- defaults/main.yml | 13 +-- handlers/main.yml | 2 +- tasks/nginx.yaml | 6 +- tasks/uwsgi.yaml | 2 +- templates/nginx/app_uwsgi_nginx.conf | 2 +- templates/supervisor/app_supervisor.conf | 4 +- templates/uwsgi/app_uwsgi.ini | 6 +- vars/main.yml | 14 +-- 9 files changed, 99 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index e7bd29d..1ca75ae 100644 --- a/README.md +++ b/README.md @@ -17,42 +17,81 @@ theoretically work on older versions of Ubuntu or Debian based systems. Role Variables -------------- -### Default Variables +There are a few crucial variables that you need to configure for your particular WSGI powered app. They are broken up +into sections and described below: -TODO - Explanation +### App Settings -# Web root paths + app name + home -app_name: app -web_root_path: /srv/www -web_server_group: www-data -app_home: "{{ web_root_path }}/{{ app_name }}_webapp" +- app_name: + - The name of WSGI app to manage via this role. + - Used as a prefix through out the role. +- app_root_path: + - The path to the root folder of the app. + - Default: {{ web_root_path }}/{{ app_name }}_webapp" -# NGINX -nginx_hostname: localhost -nginx_app_static: "{{ app_home }}/{{ app_name }}/static/" +### NGINX -# UWSGI -uwsgi_port: 8001 -uwsgi_app_executable: "app:make_wsgi_app()" +- app_nginx_hostname: + - The DNS hostname that the application serves. + - Default: localhost +- app_nginx_app_static: + - The path to the static elements of the site (templates, CSS, images, etc.) + - Default: app_root_path/app_name/static/ +### UWSGI + +- app_uwsgi_port: + - The port number that the WSGI runs on and accepts requests forwarded from NGINX. + - Default: 8001 +- app_uwsgi_executable: + - The method executed by UWSGI to create a WSGI running app. Usually a WSGI factory method or module in the app. + - Default: app:make_wsgi_app() + +### 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. + +- web_root_path: + - The root of the entire web app structure include configuration and logging. + - Default: /srv/www +- web_server_group: + - The user group responsible for starting, stopping and managing the web and app servers on the target machine. + - Default: www-data ### Main (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: -- web_user: The non-root user who is allowed to control web + app servers on the target machine. - (Default: current user) -- virtualenv_root: The common root directory of Python virtual environments associated with running the UWSGI app + - server. (Default: /srv/www/virtualenvs/) -- uwsgi_venv: The virtual environment where UWSGI is installed. (Default: virtualenv_root/uwsgi) -- app_venv: The virtual environment where the dependencies of the WSGI app is installed. - (Default: virtualenv_root/app_name) -- nginx_app_conf: The filename of the NGINX configuration for the app. (Default: app_name_uwsgi_nginx.conf) -- supervisor_app_config: The filename of the supervisor configuration for the app. (Default: app_name_supervisor.conf) -- uwsgi_config: The path to the UWSGI configurations. (Default: /srv/www/config/uwsgi) -- uwsgi_app_ini: The filename of the UWSGI INI configuration for the app. (Default: app_name_uwsgi.ini) -- uwsgi_service_name: The name of the UWSGI setup for the app according to supervisor. (Default: app_name_uwsgi) +- web_user: + - The non-root user who is allowed to control web + app servers on the target machine. + - Default: current user +- virtualenv_root_path: + - The common root directory of Python virtual environments associated with running the + UWSGI app + server. + - Default: /srv/www/virtualenvs/ +- uwsgi_venv: + - The virtual environment where UWSGI is installed. + - Default: virtualenv_root/uwsgi +- app_venv: + - The virtual environment where the dependencies of the WSGI app is installed. + - Default: virtualenv_root/app_name +- nginx_app_conf: + - The filename of the NGINX configuration for the app. + - Default: app_name_uwsgi_nginx.conf +- supervisor_app_config: + - The filename of the supervisor configuration for the app. + - Default: app_name_supervisor.conf +- uwsgi_config_path: + - The path to the UWSGI configurations. + - Default: /srv/www/config/uwsgi +- uwsgi_app_ini: + - The filename of the UWSGI INI configuration for the app. + - Default: app_name_uwsgi.ini +- uwsgi_service_name: + - The name of the UWSGI setup for the app according to supervisor. + - Default: app_name_uwsgi Example Playbook ---------------- @@ -66,10 +105,13 @@ app_name, nginx_hostname and uwsgi_app_executable parameters especially. roles: - { role: ansible-nginx-uwsgi-supervisor, app_name: app, - nginx_hostname: app.domain.net, - uwsgi_port: 8080, - uwsgi_app_executable: "app.build:make_wsgi_app()" } - + app_nginx_hostname: app.domain.net, + app_uwsgi_port: 8080, + app_uwsgi_executable: "app.build:make_wsgi_app()" } + +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. + Default File Structure ---------------------- @@ -100,8 +142,9 @@ 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.amber-penguin-software.ca/ +This role is a spin-off of the technology developed for the [Rookeries project] (http://rookeri.es/) diff --git a/defaults/main.yml b/defaults/main.yml index 69aecc8..ae59fbd 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -2,15 +2,16 @@ # defaults file for ansible-nginx-uwsgi-supervisor # Web root paths + app name + home -app_name: app web_root_path: /srv/www web_server_group: www-data -app_home: "{{ web_root_path }}/{{ app_name }}_webapp" + +app_name: app +app_root_path: "{{ web_root_path }}/{{ app_name }}_webapp" # NGINX -nginx_hostname: localhost -nginx_app_static: "{{ app_home }}/{{ app_name }}/static/" +app_nginx_hostname: localhost +app_nginx_static_path: "{{ app_root_path }}/{{ app_name }}/static/" # UWSGI -uwsgi_port: 8000 -uwsgi_app_executable: "app:make_wsgi_app()" +app_uwsgi_port: 8000 +app_uwsgi_executable: "app:make_wsgi_app()" diff --git a/handlers/main.yml b/handlers/main.yml index 6acd013..e0fe4d3 100644 --- a/handlers/main.yml +++ b/handlers/main.yml @@ -1,7 +1,7 @@ --- # handlers file for ansible-nginx-uwsgi-supervisor - name: restart uwsgi app - supervisorctl: name={{ uwsgi_service_name }} state=restarted config=/etc/supervisor/supervisor.conf + supervisorctl: name={{ uwsgi_app_service_name }} state=restarted config=/etc/supervisor/supervisor.conf sudo: yes - name: restart supervisord diff --git a/tasks/nginx.yaml b/tasks/nginx.yaml index abcd65e..9e3f0fa 100644 --- a/tasks/nginx.yaml +++ b/tasks/nginx.yaml @@ -4,13 +4,13 @@ sudo: yes - name: configure nginx - template: src=nginx/app_uwsgi_nginx.conf dest=/etc/nginx/sites-available/{{ nginx_app_conf }} + template: src=nginx/app_uwsgi_nginx.conf dest=/etc/nginx/sites-available/{{ nginx_app_config }} sudo: yes - name: link to enable nginx configuration file: state=link - src=/etc/nginx/sites-available/{{ nginx_app_conf }} - path=/etc/nginx/sites-enabled/{{ nginx_app_conf }} + src=/etc/nginx/sites-available/{{ nginx_app_config }} + path=/etc/nginx/sites-enabled/{{ nginx_app_config }} sudo: yes - name: disable default configuration diff --git a/tasks/uwsgi.yaml b/tasks/uwsgi.yaml index 2381cb0..24aaad4 100644 --- a/tasks/uwsgi.yaml +++ b/tasks/uwsgi.yaml @@ -4,5 +4,5 @@ sudo: yes - name: configure app on uwsgi server - template: src=uwsgi/app_uwsgi.ini dest={{ uwsgi_config }}/{{ uwsgi_app_ini }} + template: src=uwsgi/app_uwsgi.ini dest={{ uwsgi_config_path }}/{{ uwsgi_app_ini }} sudo: yes diff --git a/templates/nginx/app_uwsgi_nginx.conf b/templates/nginx/app_uwsgi_nginx.conf index 39add26..170ad02 100644 --- a/templates/nginx/app_uwsgi_nginx.conf +++ b/templates/nginx/app_uwsgi_nginx.conf @@ -5,7 +5,7 @@ server { error_log {{ web_root_path }}/logs/nginx/{{ app_name }}-error.log info; location /static/ { - alias {{ nginx_app_static }}; + alias {{ app_nginx_static_path }}; } location / { diff --git a/templates/supervisor/app_supervisor.conf b/templates/supervisor/app_supervisor.conf index 6e7afd3..b0f37d9 100644 --- a/templates/supervisor/app_supervisor.conf +++ b/templates/supervisor/app_supervisor.conf @@ -1,7 +1,7 @@ ; UWSGI for {{ app_name }} -[program:{{ uwsgi_service_name }}] +[program:{{ uwsgi_app_service_name }}] user={{ web_server_group }} -command={{ uwsgi_venv }}/bin/uwsgi --ini {{ uwsgi_config }}/{{ uwsgi_app_ini }} +command={{ uwsgi_venv }}/bin/uwsgi --ini {{ uwsgi_config_path }}/{{ uwsgi_app_ini }} stopsignal=TERM stdout_logfile = {{ web_root_path }}/logs/supervisor/{{ app_name }}-application.log stdout_logfile_backups = 5 diff --git a/templates/uwsgi/app_uwsgi.ini b/templates/uwsgi/app_uwsgi.ini index 445b9cc..84ba7ff 100644 --- a/templates/uwsgi/app_uwsgi.ini +++ b/templates/uwsgi/app_uwsgi.ini @@ -1,8 +1,8 @@ [uwsgi] -socket = :{{ uwsgi_port }} +socket = :{{ app_uwsgi_port }} master = true processes = 8 -chdir = {{ app_home }} +chdir = {{ app_root_path }} virtualenv = {{ app_venv }} -module = {{ uwsgi_app_executable }} +module = {{ app_uwsgi_executable }} diff --git a/vars/main.yml b/vars/main.yml index 32faf76..bd0d4b3 100644 --- a/vars/main.yml +++ b/vars/main.yml @@ -1,21 +1,21 @@ --- # vars file for ansible-nginx-uwsgi-supervisor -# Web root paths + app name + home +# User web_user: "{{ ansible_env.SUDO_USER }}" # Virtualenvs -virtualenv_root: "{{ web_root_path }}/virtualenvs" -uwsgi_venv: "{{ virtualenv_root }}/uwsgi" -app_venv: "{{ virtualenv_root }}/{{ app_name }}" +virtualenv_root_path: "{{ web_root_path }}/virtualenvs" +uwsgi_venv: "{{ virtualenv_root_path }}/uwsgi" +app_venv: "{{ virtualenv_root_path }}/{{ app_name }}" # NGINX -nginx_app_conf: "{{ app_name }}_uwsgi_nginx.conf" +nginx_app_config: "{{ app_name }}_uwsgi_nginx.conf" # Supervisor supervisor_app_config: "{{ app_name }}_supervisor.conf" # UWSGI -uwsgi_config: "{{ web_root_path }}/config/uwsgi" +uwsgi_config_path: "{{ web_root_path }}/config/uwsgi" uwsgi_app_ini: "{{ app_name }}_uwsgi.ini" -uwsgi_service_name: "{{ app_name }}_uwsgi" +uwsgi_app_service_name: "{{ app_name }}_uwsgi"