logo

# Ansible Playbooks

Ansible Lint (opens new window)

The Mint System (opens new window) collection of Ansible playbooks and roles.

# Requirements

# Usage

Clone this repository.

git clone https://github.com/Mint-System/Ansible-Playbooks.git

Set this task alias.

alias task=./task

# Setup

Navigate to the playbook folder.

cd Ansible-Playbooks

Generate a password file for Ansible vault.

task generate-passwordfile $PASSWORD

Install Ansible and Python dependencies.

task install

Create an inventory and configure a role.

Ansbile Documentation > Build Your Inventory (opens new window)

# Docs

# Roles

Role dependency graph:

Role details:

Role Description
bigbluebutton-exporter Deploy BigBlueButton exporter container.
bigbluebutton Install BigBlueButton with https and greenlight.
blackbox-exporter Deploy Blackbox exporter container.
bookstack Deploy BookStack container.
cadvisor Deploy cAdvisor Docker container.
cargo Setup Rust toolchain and cargo package manager.
certbot Deploy Let's Encrypt certificates.
clean Cleanup Ansible roles.
commento Deploy Commento container.
debug Debug Ansible variables.
docker Install Docker for Ubuntu and CentOS.
docker-compose Deploy Docker Compose project.
docker-network Configure Docker network.
docker-swarm Configure Docker Swarm.
docker-volume Configure Docker volume.
elasticsearch Deploy Elasticsearch Docker cluster.
fail2ban Install and configure fail2ban.
fathom Deploy Fathom container.
fstab Configure the fstab file.
grafana Deploy Grafana Docker container.
iam Configures users and groups.
innernet-client Setup WireGuard based internal network.
innernet-server Setup WireGuard based internal network.
keycloak Deploy Keycloak Docker container.
keycloak-client Configure Keycloak client.
kibana Deploy Kibana Docker container.
locale Set system locale.
loki Deploy Loki container.
logstash Deploy Logstash Docker container.
maintenance Maintain operating system and disk space.
metricbeat Deploy Metricbeat Docker container.
moodle Deploy Moodle container.
mysql Deploy MySQL database container.
nextcloud Deploy Nextcloud container.
nextcloud-apps Install, update and remove Nextcloud apps.
nextcloud-exporter Deploy Nextcloud exporter container.
nginx Deploy Nginx proxy with Certbot.
nginx-waf Deploy Nginx with ModSecurity and Core Rule Set.
node-exporter Deploy Node exporter container and install custom metric script.
odoo Deploy Odoo container.
odoo-apps Install Odoo apps from file, url, public or private GitHub repo.
odoo-data Generate Odoo data modules.
odoo-databases Configure Odoo databases.
odoo-enterprise Checkout the Odoo Enterprise git repository.
odoo-patches Apply custom Odoo patches.
odoo-scripts Install Odoo scripts.
onlyoffice-documentserver Deploy OnlyOffice Document Server container.
openldap Deploy OpenLDAP Docker container.
package Set env vars and install packages.
pgadmin Install pgAdmin container.
postgres Deploy PostgreSQL database container.
postgres-exporter Deploy PostgreSQL exporter container.
prometheus Deploy Prometheus Docker container.
promtail Deploy Promtail container.
redis Deploy Redis container.
remark42 Deploy Remark42 container.
resolv Manage resolv configuration.
restic-client Configure Restic client backup jobs.
restic-server Deploy Restic server container.
s3cmd Install and configure s3cmd.
simple-mail-forwarder Deploy Simple Mail Forwarder container container.
systemd Setup systemd service.
ufw Configure UFW rules.
update Install system and package updates.
vercel Manage vercel domain and dns entries.
wordpress Deploy WordPress container.

WIP:

Role Description
collabora-code Deploy Collabora Code container.
coturn Deploy Coturn container.
birt Deploy BIRT container.
synapse Deploy Matrix Synapse container.

# 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.
ansible-playbook -i inventories/setup -i inventories/odoo -i inventories/proxy play-odoo.yml

Deploy Odoo stack.
ansible-playbook -i inventories/odoo play-odoo.yml

Deploy role only.
ansible-playbook -i inventories/odoo play-odoo.yml -t postgres

Deploy without dependencies.
ansible-playbook -i inventories/odoo play-odoo.yml --skip-tags depends

Deploy role to specific host.
ansible-playbook -i inventories/odoo play-odoo.yml -t docker -l host.example.com

Deploy role to specific group with non-default user.
ansible-playbook -i inventories/odoo play-odoo.yml -t docker -l europe -u username

Clean Odoo stack.
ansible-playbook -i inventories/odoo play-clean.yml -t odoo,odoo-volume,odoo-data-dir,postgres,postgres-volume

Clean role only.
ansible-playbook -i inventories/odoo play-clean.yml -t docker-network

Clean dry run.
ansible-playbook -i inventories/odoo play-odoo.yml -t odoo --check

Install odoo-scripts and odoo-apps locally.
ansible-playbook -i inventories/odoo play-localhost.yml --skip-tags depends

List all Odoo databses.
ansible all -i inventories/odoo -a "docker-postgres-list -c "

# Quality

Lint the project using Ansible lint.

task lint

# Configuration

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

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"

# Guidelines

Every role folder must contain a README.md file.

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

# Naming

Template for role vars:

# Basics:
# Url to Docker repsitory
ROLENAME_image: URL
ROLENAME_hostname: SHORTNAME + COUNTER
ROLENAME_port:
ROLENAME_volume_name: SHORTNAME_data + COUNTER
ROLENAME_data_dir: /usr/share/SHORTNAME + COUNTER
# Database connection:
ROLENAME_db_type: mysql
ROLENAME_db_user:
ROLENAME_db_password: "{{ vault_ROLENAME_db_password }}"
ROLENAME_db_hostname:
ROLENAME_db_name:
# Credentials user:
ROLENAME_user:
ROLENAME_password: "{{ vault_ROLENAME_password }}"
# Credentials admin:
ROLENAME_admin_user:
ROLENAME_admin_password: "{{ vault_ROLENAME_admin_password }}"
# Named database connection:
ROLENAME_postgres_hostname:
ROLENAME_postgres_user:
ROLENAME_postgres_password: "{{ vault_ROLENAME_postgres_password }}"
# SMTP
ROLENAME_smtp_hostname:
ROLENAME_smtp_auth:
ROLENAME_smtp_secure:
ROLENAME_smtp_port:
ROLENAME_smtp_domain:
ROLENAME_smtp_from:
ROLENAME_smtp_username:
ROLENAME_smtp_password:

Role names must be lower case and may contain a -.

# Role 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