Table of Contents

• Blender Web Playbooks
• Adding to a new project
• Assumptions
• General usage

Blender Web Playbooks

Ansible playbooks located in this directory are used by Blender Institute staff to manage installation and continuous deployment of various web projects.

While the playbooks can be used as reference for another production or staging installation (e.g. you can find all the required packages in install.yaml, templates of web server configuration under templates/ and variables such as domain names or paths where back-end code is located in vars_common.yaml), they will not provide you with a working installation if you run them "as is".

It should be possible, however, to adjust the playbooks by copying a directory under environments/ and adjusting variables in that directory. Refer to Ansible documentation for details about inventory variables.

Adding to a new project

This section only applies to new projects, not existing ones that already have playbooks directory.

In the project's directory, create playbooks directory.

mkdir playbooks

The rest of this section is assumed to be happening inside that playbooks/ directory:

cd playbooks

Playbooks directory is assumed to have the following structure:

playbooks
├── ansible.cfg -> shared/ansible.cfg                  # symlink to shared/ansible.cfg
├── ansible.sh -> shared/ansible.sh                    # symlink to shared/ansible.sh
├── environments
│   ├── environments/production                        # inventory with production variables and hosts
│   │   ├── environments/production/group_vars
│   │   │   └── environments/production/group_vars/all
│   │   │       ├── environments/production/group_vars/all/00_vars_common.yaml -> ../../../../vars_common.yaml
│   │   │       └── environments/production/group_vars/all/01_vars.yaml
│   │   └── environments/production/hosts.yaml
│   └── environments/staging                           # inventory with staging variables and hosts
│       ├── environments/staging/group_vars
│       │   └── environments/staging/group_vars/all
│       │       ├── environments/staging/group_vars/all/00_vars_common.yaml -> ../../../../vars_common.yaml
│       │       └── environments/staging/group_vars/all/01_vars.yaml
│       └── environments/staging/hosts.yaml
├── README.md
├── shared                                             # this repository as a submodule
├── templates
│   └── templates/nginx
│       ├── templates/nginx/application.conf           # configuration of nginx at the application server
│       └── templates/nginx/ingress.conf               # configuration of nginx at the ingress (SSL terminating) server
└── vars_common.yaml                                   # variables shared between production and staging via 00_vars_common.yaml symlink

Add this repository under playbooks/shared directory:

git submodule add https://projects.blender.org/infrastructure/web-playbooks shared

Create symlinks to shared Ansible configuration files:

ln -s shared/ansible.cfg ansible.cfg
ln -s shared/ansible.sh  ansible.sh

Copy a vars_common.yaml from the example and modify its content to fit the project:

cp shared/vars_common.example.yaml vars_common.yaml

Create a basic template for nginx configuration at the application server in templates/nginx/application.conf:

{% extends "templates/nginx/base_application.conf" %}
{# uncomment and add aditional location blocks here:
{% block extra_locations %}
{% endblock extra_locations %}
#}

Create a basic template for nginx configuration at the ingress server in templates/nginx/ingress.conf:

{% extends "templates/nginx/base_ingress.conf" %}
{# uncomment and add aditional location blocks here:
{% block extra_locations %}
{% endblock extra_locations %}
#}

Assumptions

Playbooks assume the following about the project:

• project has a requirements_prod.txt which is pip installed on each deploy;
• project configures its own SSL certificate using certbot;
• OS of the target hosts is Ubuntu 24.04 LTS (might still work with 22.04 and 20.04, but is no longer tested);

General usage

See usage documentation.