logo

Ansible Build

The Mint Systemopen in new window collection of Ansible playbooks and roles.

Requirements

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 Inventoryopen in new window

Docs

Scripts

Some roles install helper scripts. They can be used without Ansible. See scripts for details.

Roles

List of all available Ansible roles.

RoleDescription
bigbluebutton_exporterDeploy BigBlueButton exporter container.
bigbluebuttonInstall BigBlueButton with https and greenlight.
birtDeploy BIRT container.
blackbox_exporterDeploy Blackbox exporter container.
bookstackDeploy BookStack container.
cadvisorDeploy cAdvisor Docker container.
cargoSetup Rust toolchain and cargo package manager.
certbotDeploy Let's Encrypt certificates.
cleanCleanup Ansible roles.
collabora_codeDeploy Collabora Code container.
commentoDeploy Commento container.
cronSetup cron jobs.
debugDebug Ansible variables.
dindDeploy Docker in Docker container.
docker_composeDeploy Docker Compose project.
docker_networkConfigure Docker network.
docker_swarmConfigure Docker Swarm.
docker_volumeConfigure Docker volume.
dockerInstall Docker for Ubuntu and CentOS.
dozzleDeploy Dozzle container.
dribdatDeploy dribdat container.
elasticsearchDeploy Elasticsearch Docker cluster.
fail2banInstall and configure fail2ban.
fathomDeploy Fathom container.
fstabConfigure the fstab file.
gitCheckout Git repositories.
giteaDeploy Gitea container.
grafanaDeploy Grafana Docker container.
htpasswdConfigure .htpasswd basic auth file.
iamConfigures users and groups.
innernet_clientSetup WireGuard based internal network.
innernet_serverSetup WireGuard based internal network.
jenkinsDeploy Jenkins container.
keycloak_clientConfigure Keycloak client.
keycloakDeploy Keycloak Docker container.
kibanaDeploy Kibana Docker container.
localeSet system locale.
logstashDeploy Logstash Docker container.
lokiDeploy Loki container.
mailhogDeploy MailHog Docker container.
maintenanceMaintain operating system and disk space.
mariadbDeploy MariaDB database container.
matomoDeploy Matomo container.
metricbeatDeploy Metricbeat Docker container.
moodleDeploy Moodle container.
mysqlDeploy MySQL database container.
nextcloud_appsInstall, update and remove Nextcloud apps.
nextcloud_exporterDeploy Nextcloud exporter container.
nextcloudDeploy Nextcloud container.
nginx_wafDeploy Nginx with ModSecurity and Core Rule Set.
nginxDeploy Nginx proxy with Certbot.
node_exporterDeploy Node exporter container and install custom metric script.
odoo_appsInstall Odoo apps from file, url, public or private GitHub repo.
odoo_dataGenerate Odoo data modules.
odoo_databasesConfigure Odoo databases.
odoo_enterpriseCheckout the Odoo Enterprise git repository.
odoo_patchesApply custom Odoo patches.
odoo_scriptsInstall Odoo scripts.
odooDeploy Odoo container.
onlyoffice_documentserverDeploy OnlyOffice Document Server container.
openldapDeploy OpenLDAP Docker container.
packageSet env vars and install packages.
pgadminInstall pgAdmin container.
postfixDeploy Postfix relay host.
postgres_exporterDeploy PostgreSQL exporter container.
postgresDeploy PostgreSQL database container.
prometheusDeploy Prometheus Docker container.
promtailDeploy Promtail container.
rcloneSync files with RClone.
rabbitDeploy RabbitMQ container.
redisDeploy Redis container.
remark42Deploy Remark42 container.
resolvManage resolv configuration.
restic_clientConfigure Restic client backup jobs.
restic_serverDeploy Restic server container.
s3cmdInstall and configure s3cmd.
simple_mail_forwarderDeploy Simple Mail Forwarder container container.
supersetDeploy Apache Superset container.
systemdSetup systemd service.
ufwConfigure UFW rules.
updateInstall system and package updates.
vercelManage vercel domain and dns entries.
wordpressDeploy WordPress container.

Work in Progress:

RoleDescription
docker_hostsDocker hostname resolver..
coturnDeploy Coturn container.
synapseDeploy Matrix Synapse container.

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 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