Ansible Build
The Mint System collection of Ansible playbooks and roles.
Requirements
- Install python 3.8+ with pyenv
- 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 playbook folder.
cd Ansible-Build
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 available Ansible roles.
Role | Description |
---|---|
acme_sh | Issue & renew the free certificates. |
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. |
collabora_code | Deploy Collabora Code container. |
commento | Deploy Commento container. |
coturn | Deploy Coturn cotainer. |
cron | Setup cron jobs. |
debug | Debug Ansible variables. |
dind | Deploy Docker in Docker container. |
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. |
docker | Install Docker for Ubuntu and CentOS. |
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. |
htpasswd | Configure .htpasswd basic auth file. |
hosts | Add entries to hosts files. |
iam | Configures users and groups. |
innernet_client | Setup WireGuard based internal network. |
innernet_server | Setup WireGuard based internal network. |
jenkins | Deploy Jenkins container. |
keycloak_client | Configure Keycloak client. |
keycloak | Deploy Keycloak Docker container. |
kibana | Deploy Kibana Docker container. |
locale | Set system locale. |
logstash | Deploy Logstash Docker container. |
loki | Deploy Loki container. |
mailhog | Deploy MailHog Docker container. |
maintenance | Maintain operating system and disk space. |
mariadb | Deploy MariaDB database container. |
matomo | Deploy Matomo container. |
meilisearch | Deploy Meilisearch container. |
metricbeat | Deploy Metricbeat Docker container. |
moodle | Deploy Moodle container. |
mysql | Deploy MySQL database container. |
nextcloud_apps | Install, update and remove Nextcloud apps. |
nextcloud_exporter | Deploy Nextcloud exporter container. |
nextcloud | Deploy Nextcloud container. |
nginx_waf | Deploy Nginx with ModSecurity and Core Rule Set. |
nginx | Deploy Nginx proxy with Certbot. |
node_exporter | Deploy Node exporter container and install custom metric script. |
odoo_apps | Install Odoo apps from file, url, public or private GitHub repo. |
odoo_data | Generate Odoo data modules. |
odoo_exporter | Add nginx config for Odoo exporter path. |
odoo_enterprise | Checkout the Odoo Enterprise git repository. |
odoo_patches | Apply custom Odoo patches. |
odoo_scripts | Install Odoo scripts. |
odoo | Deploy Odoo container. |
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_exporter | Deploy PostgreSQL exporter container. |
postgres | Deploy PostgreSQL database container. |
prometheus | Deploy Prometheus Docker container. |
promtail | Deploy Promtail container. |
rclone | Sync files with RClone. |
rabbit | 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. |
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. |
Scripts
Various roles install command line tools that can be used independent of Ansible. See scripts for details.
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 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/setup play_setup.yml --skip-tags depends
Deploy role to specific host.
ansible-playbook -i inventories/setup play_setup.yml -t docker -l host.example.com
Deploy role to specific group with non-default user.
ansible-playbook -i inventories/setup play_setup.yml -t docker -l host.example.com -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/setup 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/setup 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
andnginx_config
- Create the task files
nginx.yml
andnginx_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.
- website: Website environment.
- old: Obsolete 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