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 |
---|---|
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. |
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. |
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. |
n8n | Deploy N8N 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_enterprise | Checkout the Odoo Enterprise git repository. |
odoo_exporter | Add nginx config for Odoo exporter path. |
odoo_patches | Apply custom Odoo patches. |
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. |
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 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
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