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
Targets
Some Ansible roles can be deployed to a Linux Server or to Kubernetes Cluster.
The role documentation show how to configure either deployment target.
Roles
Have a look at the Ansible roles and checkout how to configure them.
Role | Description |
---|---|
ansible_scripts | Install Ansible scripts. |
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 | Setup WireGuard based internal network. |
jenkins | Deploy Jenkins container. |
keycloak_client | Configure Keycloak client. |
k3s | Deploy Kubernetes cluster with K3s. |
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 | Configure Restic 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. |
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 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 }}"
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
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