Ansible Build

The Mint System collection of Ansible playbooks and roles.

Requirements

• Setup uv
• bash/zsh alias task='./task' with optional completion

Usage

Clone this repository.

git clone git@github.com:Mint-System/Ansible-Build.git

See task help or task for details about the project commands.

Setup

Navigate into the project folder.

cd Ansible-Build

Generate an Ansible vault id and password.

task generate-vault-password $VAULT_ID $PASSWORD

Create an Ansible configuration from the template.

cp ansible.cfg.template ansible.cfg

Install Ansible and Python dependencies.

task install

Create an inventory folder and configure a role.

Ansbile Documentation > Build Your Inventory

Roles

See roles for details or list the roles with:

task list-roles

Targets

All Ansible roles can be deployed to a Linux Server via SSH.

flowchart TD
	A[Host] -->|SSH| B[Server]

Loading

Ansible Vault

If you encrypt secrets with multiple vault identities, you can specificy the vault list in the ansible.cfg like this:

[defaults]
vault_identity_list = mint_system@.vault_pass_mint_system, sozialinfo@.vault_pass_sozialinfo

Or as an environment variable:

export ANSIBLE_VAULT_IDENTITY_LIST="mint_system@.vault_pass_mint_system, sozialinfo@.vault_pass_sozialinfo"

Alternatively you can configure the --vault-id parameter of the Ansible playbook command:

task play --vault-id mint_system@.vault_pass_mint_system ...

To decrypt single strings run this command:

task encrypt-string sozialinfo "vault_rolename_varname: secret"

Deploy

Deploy the roles to the target hosts with the following commands.

List hosts in inventory.

task list-hosts inventories/setup

Load virtualenv.

source task source

Test connection.

ansible all -m ping -i inventories/odoo

Deploy multiple inventories.

task play -i inventories/setup -i inventories/odoo plays/odoo.yml

Deploy Odoo stack.

task play -i inventories/odoo plays/odoo.yml

Deploy role only.

task play -i inventories/odoo plays/odoo.yml -t postgres

Deploy without dependencies.

task play -i inventories/setup plays/setup.yml --skip-tags depends

Deploy role to specific host.

task play -i inventories/setup plays/setup.yml -t docker -l server1

Deploy role to specific group with non-default user.

task play -i inventories/setup plays/setup.yml -t docker -l server1 -u username

Cleanup Odoo stack.

task play -i inventories/odoo plays/cleanup.yml.yml -t odoo,odoo_volume,odoo_data,postgres,postgres_volume

Cleanup role only.

task play -i inventories/setup plays/cleanup.yml.yml -t docker_network

Cleanup dry run.

task play -i inventories/odoo plays/odoo.yml -t odoo --check

List all Odoo databases.

ansible all -i inventories/odoo -a "docker-postgres-list -c {{ postgres_hostname }}"

Development

This section is about developing the Ansible Build project.

New role

The easiest way to create a new role is to copy the postgres role. Then search and replace the variable prefix within the role folder and remove unecessary files.

cp -r postgres pgbouncer
cd pgbouncer
rm -r templates files
find . -type f -exec sed -i 's/postgres/pgbouncer/g' {} \;
mv tasks/postgres.yml tasks/pgbouncer.yml

Edit the role files manually and add the roles to the playbooks.

Quality assurance

Lint the project using Ansible lint.

task lint

Mapping environment variables

Whenever possible use env variables to configure the container.

Env Config

env:
  POSTGRES_USER: "{{ postgres_user }}"
  POSTGRES_PASSWORD: "{{ postgres_password }}"
  POSTGRES_DB: "{{ postgres_db }}"

Data persistence

To persist data use Docker volumes.

Volume Mount

Mount the folder without subfolder.

volumes:
  - "{{ postgres_volume_name }}:/var/lib/postgresql/data"

For Ansible config files use file mounts.

Bind Mount

volumes:
  - "{{ nginx_data_dir }}/:/etc/nginx/conf.d/:ro"

Role documentation

Every role folder must contain a README.md file.

Mark fix-me-comments with #FIXME: <your text>.

Naming conventions

Role names must be lower case and may contain an _.

Vars that are stored in vaults are prefixed with vault_.

Template for role vars:

# Url to Docker repsitory
rolename_image:
rolename_hostname:
rolename_port:
rolename_volume_name: "{{ rolename_hostname }}"
rolename_data_dir: "/usr/share/{{ rolename_hostname }}"
rolename_password: "{{ vault_rolename_password }}"

The reference roles are postgres and odoo.

Roles and tags

Roles can have multiple tags.

Example one tag

To define a Postgres role, you would:

• Create role postges
• Assign the tag postgres
• Create a task file postgres.yml

Example multiple tags

To define a Nginx role with a config tag, you would:

• Create role nginx
• Assign the tags nginx and nginx_config
• Create the task files nginx.yml and nginx_config.yml

In the main.yml you would include the tasks as followed:

- name: "Include {{ role_name }} config tasks"
  include_tasks: "{{ role_name }}-config.yml"
  when: nginx_data_dir is defined
  tags:
    - nginx
    - nginx_config

- name: "Include {{ role_name }} tasks"
  include_tasks: "{{ role_name }}.yml"
  when: nginx_image is defined
  tags:
    - nginx

Host aliases

Whenever a role is applied to the same host multiple times, you can create multiple aliases for the same host. Append a selected suffix to make a distinction between the aliases:

• main: Production environment.
• staging: Staging environment.
• dev: Development and test environment.
• upgrade: Upgrade environment.

Here is an example of an host with two aliases:

all:
  hosts:
    server_web:
      ansible_host: server.example.com
    server_main:
      ansible_host: server.example.com