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 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 |
---|---|
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. |
crowdsec | Deploy crowdsec container. |
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. |
n8n | Deploy N8N 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. |
Targets
All Ansible roles can be deployed to a Linux Server via SSH.
flowchart TD A[Host] -->|SSH| B[Server]
Some Ansible roles can be deployed to a Kubernetes Cluster.
Ansible Vault
If y'ou 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
Template for role vars:
# Basics:
# Url to Docker repsitory
rolename_image:
rolename_hostname:
rolename_port:
rolename_volume_name: "{{ rolename_hostname }}"
rolename_data_dir: "/usr/share/{{ rolename_hostname }}"
# Database connection:
rolename_db_type:
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 connection:
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 an _
.
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.
- 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