Ansible Playbooks

The Mint System collection of Ansible playbooks and roles.

Requirements

• Install python 3.8+ with pyenv

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

Docs

Roles

List of all avaialable Ansible roles.

Role	Description
bigbluebutton-exporter	Deploy BigBlueButton exporter container.
bigbluebutton	Install BigBlueButton with https and greenlight.
birt	Deploy BIRT container.
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.
cron	Setup cron jobs.
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.
gitea	Deploy Gitea container.
grafana	Deploy Grafana Docker container.
htpasswd	Configure .htpasswd basic auth file.
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.
mariadb	Deploy MariaDB database container.
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.
postfix	Deploy Postfix relay host.
postgres	Deploy PostgreSQL database container.
postgres-exporter	Deploy PostgreSQL exporter container.
prometheus	Deploy Prometheus Docker container.
promtail	Deploy Promtail container.
rclone	Sync files with RClone.
redis	Deploy RabbitMQ 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.

Work in progress:

Role	Description
coturn	Deploy Coturn container.
synapse	Deploy Matrix Synapse container.
collabora-code	Deploy Collabora Code 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,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 {{ postgres_hostname }}"

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