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

Have a look at the Ansible roles and check how to configure them.

Role	Description
acme_sh	Issue & renew the free certificates.
alertmanager	Deploy Alertmanager container.
ansible_scripts	Install Ansible scripts.
bigbluebutton	Install BigBlueButton with https and greenlight.
bigbluebutton_exporter	Deploy BigBlueButton exporter container.
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.
collabora_code	Deploy Collabora Code container.
commento	Deploy Commento container.
coturn	Deploy Coturn cotainer.
cron	Setup cron jobs.
crowdsec	Deploy CrowdSec container.
crowdsec_firewall_bouncer	Deploy CrowdSec Firewall Bouncer.
debug	Debug Ansible variables.
dind	Deploy Docker in Docker container.
docker	Install Docker for Ubuntu and CentOS.
docker_compose	Deploy Docker Compose project.
docker_hosts	Docker hostname resolver.
docker_network	Configure Docker network.
docker_swarm	Configure Docker Swarm.
docker_volume	Configure Docker volume.
dozzle	Deploy Dozzle container.
dribdat	Deploy dribdat container.
elasticsearch	Deploy Elasticsearch Docker cluster.
fail2ban	Install and configure fail2ban.
fathom	Deploy Fathom container.
fstab	Configure the fstab file.
git	Checkout Git repositories.
gitea	Deploy Gitea container.
grafana	Deploy Grafana Docker container.
hosts	Add entries to hosts files.
htpasswd	Configure .htpasswd basic auth file.
iam	Configures users and groups.
innernet	Setup WireGuard based internal network.
jenkins	Deploy Jenkins container.
k3s	Deploy Kubernetes cluster with K3s.
keycloak	Deploy Keycloak Docker container.
keycloak_client	Configure Keycloak client.
kibana	Deploy Kibana Docker container.
locale	Set system locale.
logstash	Deploy Logstash Docker container.
loki	Deploy Loki container.
mailhog	Deploy MailHog Docker container.
mailpit	Deploy Mailpit Docker container.
maintenance	Maintain operating system and disk space.
mariadb	Deploy MariaDB database container.
matomo	Deploy Matomo container.
meilisearch	Deploy Meilisearch container.
metabase	Deploy Metabase Docker container.
metricbeat	Deploy Metricbeat Docker container.
moodle	Deploy Moodle container.
mysql	Deploy MySQL database container.
n8n	Deploy N8N container.
n8n_exporter	Add nginx config for N8N exporter path.
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 or url.
odoo_data	Generate Odoo data modules.
odoo_enterprise	Checkout the Odoo Enterprise git repository.
odoo_exporter	Add nginx config for Odoo exporter path.
odoo_patches	Apply custom Odoo patches.
odoo_repos	Setup Odoo modules public or private GitHub repo.
odoo_scripts	Install Odoo scripts.
onlyoffice_documentserver	Deploy OnlyOffice Document Server container.
openldap	Deploy OpenLDAP Docker container.
packages	Set env vars and install packages.
pgadmin	Deploy pgAdmin container.
php_fpm	Deploy PHP-FPM 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.
rabbit	Deploy RabbitMQ container.
rclone	Sync files with RClone.
redis	Deploy Redis container.
remark42	Deploy Remark42 container.
resolv	Manage resolv configuration.
restic	Configure Restic backup jobs.
restic_server	Deploy Restic server container.
restic_exporter	Add nginx config for Restic exporter path.
s3cmd	Install and configure s3cmd.
simple_mail_forwarder	Deploy Simple Mail Forwarder container container.
superset	Deploy Apache Superset container.
systemd	Setup systemd service.
timezone	Define timezone.
ufw	Configure UFW rules.
update	Install system and package updates.
vercel	Manage vercel domain and dns entries.
wordpress	Deploy WordPress container.

Targets

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

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

Loading

Some Ansible roles can be deployed to a Kubernetes Cluster.

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:

ansible-playbook --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.

ansible-playbook -i inventories/setup -i inventories/odoo plays/odoo.yml

Deploy Odoo stack.

ansible-playbook -i inventories/odoo plays/odoo.yml

Deploy role only.

ansible-playbook -i inventories/odoo plays/odoo.yml -t postgres

Deploy without dependencies.

ansible-playbook -i inventories/setup plays/setup.yml --skip-tags depends

Deploy role to specific host.

ansible-playbook -i inventories/setup plays/setup.yml -t docker -l host.example.com

Deploy role to specific group with non-default user.

ansible-playbook -i inventories/setup plays/setup.yml -t docker -l host.example.com -u username

Clean Odoo stack.

ansible-playbook -i inventories/odoo plays/clean.yml.yml -t odoo,odoo_volume,odoo_data,postgres,postgres_volume

Clean role only.

ansible-playbook -i inventories/setup plays/clean.yml.yml -t docker_network

Clean dry run.

ansible-playbook -i inventories/odoo plays/odoo.yml -t odoo --check

Install odoo_scripts and odoo_apps locally.

ansible-playbook -i inventories/setup plays/localhost.yml.yml --skip-tags depends

List all Odoo databses.

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

Kubernetes

Setup the following and the role's Kubernetes variables in your localhost inventory.

k8s_kubeconfig: /home/$USERNAME/.kube/config
k8s_namespace: default

Run the Kubernetes playbook for localhost.

ansible-playbook -i inventories/k8s plays/k8s.yml.yml -l localhost

Development

This section is about developing the Ansible Build project.

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"

Docs

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.

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

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.
• int: Staging environment.
• dev: Development and test environment.
• upgrade: Upgrade environment.
• dep: Deprecated environment.

Here is an example of an host with two aliases:

all:
  hosts:
    zeus_web:
      ansible_host: zeus.mint-system.com
    zeus_main:
      ansible_host: zeus.mint-system.com