{"id":13580796,"url":"https://github.com/nickjj/ansible-docker","last_synced_at":"2025-05-16T10:07:14.766Z","repository":{"id":11722123,"uuid":"70362223","full_name":"nickjj/ansible-docker","owner":"nickjj","description":"Install / Configure Docker and Docker Compose using Ansible.","archived":false,"fork":false,"pushed_at":"2024-07-30T22:09:59.000Z","size":197,"stargazers_count":762,"open_issues_count":8,"forks_count":225,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-05-08T20:50:11.688Z","etag":null,"topics":["ansible","docker","docker-compose"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickjj.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-08T23:07:06.000Z","updated_at":"2025-03-28T18:35:43.000Z","dependencies_parsed_at":"2024-01-14T14:29:33.398Z","dependency_job_id":"6ce62c97-c1d9-4ec6-9183-d2719ce17b9b","html_url":"https://github.com/nickjj/ansible-docker","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickjj%2Fansible-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickjj%2Fansible-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickjj%2Fansible-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickjj%2Fansible-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickjj","download_url":"https://codeload.github.com/nickjj/ansible-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509476,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","docker","docker-compose"],"created_at":"2024-08-01T15:01:55.168Z","updated_at":"2025-05-16T10:07:09.756Z","avatar_url":"https://github.com/nickjj.png","language":"Python","funding_links":[],"categories":["Python","docker-compose"],"sub_categories":[],"readme":"## What is ansible-docker? ![CI](https://github.com/nickjj/ansible-docker/workflows/CI/badge.svg?branch=master)\n\nIt is an [Ansible](http://www.ansible.com/home) role to:\n\n- Install Docker (editions, channels and version pinning are all supported)\n- Install Docker Compose v2 and / or Docker Compose v1 (version pinning is supported)\n- Install the `docker` PIP package so Ansible's `docker_*` modules work\n- Manage Docker registry login credentials\n- Configure 1 or more users to run Docker without needing root access\n- Configure the Docker daemon's options and environment variables\n- Configure a cron job to run Docker clean up commands\n\n## Why would you want to use this role?\n\nIf you're like me, you probably love Docker. This role provides everything you\nneed to get going with a production ready Docker host.\n\nBy the way, if you don't know what Docker is, or are looking to become an expert\nwith it then check out\n[Dive into Docker: The Complete Docker Course for Developers](https://diveintodocker.com/?utm_source=ansibledocker\u0026utm_medium=github\u0026utm_campaign=readmetop).\n\n## Supported platforms\n\n- Ubuntu 20.04 LTS (Focal Fossa)\n- Ubuntu 22.04 LTS (Jammy Jellyfish)\n- Debian 11 (Bullseye)\n- Debian 12 (Bookworm)\n\nPrevious releases may or may not work but they're not officially supported.\n\n---\n\n*You are viewing the master branch's documentation which might be ahead of the\nlatest release. [Switch to the latest release](https://github.com/nickjj/ansible-docker/tree/v2.5.0).*\n\n---\n\n## Quick start\n\nThe philosophy for all of my roles is to make it easy to get going, but provide\na way to customize nearly everything.\n\n### What's configured by default?\n\nThe latest stable release of Docker CE and Docker Compose v2 will be installed,\nDocker disk clean up will happen once a week and Docker container logs will be\nsent to `journald`.\n\n### Example playbook\n\n```yml\n---\n\n# docker.yml\n\n- name: Example\n  hosts: \"all\"\n  become: true\n\n  roles:\n    - role: \"nickjj.docker\"\n      tags: [\"docker\"]\n```\n\nUsage: `ansible-playbook docker.yml`\n\n### Installation\n\n`$ ansible-galaxy install nickjj.docker`\n\n## Default role variables\n\n### Installing Docker\n\n#### Channel\n\nDo you want to use the \"stable\" or \"test\" channel? You can add more than one\n(order matters).\n\n```yml\ndocker__channel: [\"stable\"]\n```\n\n#### Version\n\n- When set to \"\", the current latest version of Docker will be installed\n- When set to a specific version, that version of Docker will be installed and pinned\n\n```yml\ndocker__version: \"\"\n\n# For example, pin it to 25.0.\ndocker__version: \"25.0\"\n\n# For example, pin it to a more precise version of 25.0.\ndocker__version: \"25.0.5\"\n```\n\n*Pins are set with `*` at the end of the package version so you will end up\ngetting minor and security patches unless you pin an exact version.*\n\n##### Upgrade strategy\n\n- When set to `\"present\"`, running this role in the future won't install newer\nversions (if available)\n- When set to `\"latest\"`, running this role in the future will install newer\nversions (if available)\n\n```yml\ndocker__state: \"present\"\n```\n\n##### Downgrade strategy\n\nThe easiest way to downgrade would be to uninstall the Docker package manually\nand then run this role afterwards while pinning whatever specific Docker version\nyou want.\n\n```sh\n# An ad-hoc Ansible command to stop and remove the Docker CE package on all hosts.\nansible all -m systemd -a \"name=docker-ce state=stopped\" \\\n  -m apt -a \"name=docker-ce autoremove=true purge=true state=absent\" -b\n```\n\n### Installing Docker Compose v2\n\nDocker Compose v2 will get apt installed using the official\n`docker-compose-plugin` that Docker manages.\n\n#### Version\n\n- When set to \"\", the current latest version of Docker Compose v2 will be installed\n- When set to a specific version, that version of Docker Compose v2 will be installed\nand pinned\n\n```yml\ndocker__compose_v2_version: \"\"\n\n# For example, pin it to 2.29.\ndocker__compose_v2_version: \"2.29\"\n\n# For example, pin it to a more precise version of 2.29.1.\ndocker__compose_v2_version: \"2.29.1\"\n```\n\n##### Upgrade strategy\n\nIt'll re-use the `docker__state` variable explained above in the Docker section\nwith the same rules.\n\n##### Downgrade strategy\n\nLike Docker itself, the easiest way to uninstall Docker Compose v2 is to manually\nrun the command below and then pin a specific Docker Compose v2 version.\n\n```sh\n# An ad-hoc Ansible command to remove the Docker Compose Plugin package on all hosts.\nansible all -m apt -a \"name=docker-compose-plugin autoremove=true purge=true state=absent\" -b\n```\n\n### Installing Docker Compose v1\n\nBy default this role doesn't install Docker Compose v1 since it's been\nofficially deprecated and no longer receives updates by Docker. However, this\nrole is capable of installing it. All you have to do is set\n`docker__pip_docker_compose_state: \"present\"` since this role defaults to\n`absent` for this value.\n\nTechnically both versions can be installed together since v1 is accessed with\n`docker-compose` and v2 is accessed with `docker compose` (notice the lack of\nhyphen).\n\nI'd suggest not installing v1 unless you really need it for legacy purposes. If\nyou do decide to install it you can configure which version gets installed\nbelow. If it's not set to be installed these versions are left unused:\n\n#### Version\n\n- When set to \"\", the current latest version of Docker Compose v1 will be installed\n- When set to a specific version, that version of Docker Compose v1 will be installed\nand pinned\n\n```yml\ndocker__compose_version: \"\"\n\n# For example, pin it to 1.29.\ndocker__compose_version: \"1.29\"\n\n# For example, pin it to a more precise version of 1.29.\ndocker__compose_version: \"1.29.2\"\n```\n\n*Upgrade and downgrade strategies will be explained in the other section of this\nREADME.*\n\n### Configuring users to run Docker without root\n\nA list of users to be added to the `docker` group.\n\nKeep in mind this user needs to already exist, this role will not create it. If\nyou want to create users, check out my\n[user role](https://github.com/nickjj/ansible-user).\n\nThis role does not configure User Namespaces or any other security features\nby default. If the user you add here has SSH access to your server then you're\neffectively giving them root access to the server since they can run Docker\nwithout `sudo` and volume mount in any path on your file system.\n\nIn a controlled environment this is safe, but like anything security related\nit's worth knowing this up front. You can enable User Namespaces and any\nother options with the `docker__daemon_json` variable which is explained later.\n\n```yml\n# Try to use the sudo user by default, but fall back to root.\ndocker__users: [\"{{ ansible_env.SUDO_USER | d('root') }}\"]\n\n# For example, if the user you want to set is different than the sudo user.\ndocker__users: [\"admin\"]\n```\n\n### Configuring Docker registry logins\n\nLogin to 1 or more Docker registries (such as the\n[Docker Hub](https://hub.docker.com/)).\n\n```yml\n# Your login credentials will end up in this user's home directory.\ndocker__login_become_user: \"{{ docker__users | first | d('root') }}\"\n```\n\n```yml\n# 0 or more registries to log into.\ndocker__registries:\n  - #registry_url: \"https://index.docker.io/v1/\"\n    username: \"your_docker_hub_username\"\n    password: \"your_docker_hub_password\"\n    #email: \"your_docker_hub@emailaddress.com\"\n    #reauthorize: false\n    #config_path: \"$HOME/.docker/config.json\"\n    #state: \"present\"\ndocker__registries: []\n```\n\n*Properties prefixed with \\* are required.*\n\n- `registry_url` defaults to `https://index.docker.io/v1/`\n- *`username` is your Docker registry username\n- *`password` is your Docker registry password\n- `email` defaults to not being used (not all registries use it)\n- `reauthorize` defaults to `false`, when `true` it updates your credentials\n- `config_path` defaults to your `docker__login_become_user`'s `$HOME` directory\n- `state` defaults to \"present\", when \"absent\" the login will be removed\n\n### Configuring the Docker daemon options (json)\n\nDefault Docker daemon options as they would appear in `/etc/docker/daemon.json`.\n\n```yml\ndocker__default_daemon_json: |\n  \"log-driver\": \"journald\",\n  \"features\": {\n    \"buildkit\": true\n  }\n\n# Add your own additional daemon options without overriding the default options.\n# It follows the same format as the default options, and don't worry about\n# starting it off with a comma. The template will add the comma if needed.\ndocker__daemon_json: \"\"\n```\n\n### Configure the Docker daemon options (flags)\n\nFlags that are set when starting the Docker daemon cannot be changed in the\n`daemon.json` file. By default Docker sets `-H unix://` which means that option\ncannot be changed with the json options.\n\nAdd or change the starting Docker daemon flags by supplying them exactly how\nthey would appear on the command line.\n\n```yml\n# Each command line flag should be its own item in the list.\n#\n# Using a Docker version prior to 18.09?\n#   You must set `-H fd://` instead of `-H unix://`.\ndocker__daemon_flags:\n  - \"-H unix://\"\n```\n\n*If you don't supply some type of `-H` flag here, Docker will fail to start.*\n\n### Configuring the Docker daemon environment variables\n\n```yml\ndocker__daemon_environment: []\n\n# For example, here's how to set a couple of proxy environment variables.\ndocker__daemon_environment:\n  - \"HTTP_PROXY=http://proxy.example.com:80\"\n  - \"HTTPS_PROXY=https://proxy.example.com:443\"\n```\n\n### Configuring advanced systemd directives\n\nThis role lets the Docker package manage its own systemd unit file and adjusts\nthings like the Docker daemon flags and environment variables by using\nthe systemd override pattern.\n\nIf you know what you're doing, you can override or add to any of Docker's systemd\ndirectives by setting this variable. Anything you place in this string will be\nwritten to `/etc/systemd/system/docker.service.d/custom.conf` as is.\n\n```yml\ndocker__systemd_override: \"\"\n```\n\n### Configuring Docker related cron jobs\n\nBy default this will safely clean up disk space used by Docker every Sunday at\nmidnight.\n\n```yml\n# `a` removes unused images (useful in production).\n# `f` forces it to happen without prompting you to agree.\ndocker__cron_jobs_prune_flags: \"af\"\n\n# Control the schedule of the docker system prune.\ndocker__cron_jobs_prune_schedule: [\"0\", \"0\", \"*\", \"*\", \"0\"]\n\ndocker__cron_jobs:\n  - name: \"Docker disk clean up\"\n    job: \"docker system prune -{{ docker__cron_jobs_prune_flags }} \u003e /dev/null 2\u003e\u00261\"\n    schedule: \"{{ docker__cron_jobs_prune_schedule }}\"\n    cron_file: \"docker-disk-clean-up\"\n    #user: \"{{ (docker__users | first) | d('root') }}\"\n    #state: \"present\"\n```\n\n*Properties prefixed with \\* are required.*\n\n- *`name` is the cron job's description\n- *`job` is the command to run in the cron job\n- *`schedule` is the [standard cron job](https://en.wikipedia.org/wiki/Cron#Overview)\nformat for every Sunday at midnight\n- *`cron_file` writes a cron file to `/etc/cron.d` instead of a user's individual crontab\n- `user` defaults to the first `docker__users` user or root if that's not available\n- `state` defaults to \"present\", when \"absent\" the cron file will be removed\n\n### Configuring the APT package manager\n\nDocker requires a few dependencies to be installed for it to work. You shouldn't\nhave to edit any of these variables.\n\n```yml\n# List of packages to be installed.\ndocker__package_dependencies:\n  - \"apt-transport-https\"\n  - \"ca-certificates\"\n  - \"cron\"\n  - \"gnupg2\"\n  - \"software-properties-common\"\n\n# Ansible identifies CPU architectures differently than Docker.\ndocker__architecture_map:\n  \"x86_64\": \"amd64\"\n  \"aarch64\": \"arm64\"\n  \"aarch\": \"arm64\"\n  \"armhf\": \"armhf\"\n  \"armv7l\": \"armhf\"\n\n# The Docker GPG key URL.\ndocker__apt_repository_url: \"https://download.docker.com/linux/{{ ansible_distribution | lower }}\"\n\n# The Docker GPG key checksum value.\ndocker__apt_key_checksum: \"sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570\"\n\n# The Docker upstream APT repository.\ndocker__apt_repository: \u003e\n  deb [arch={{ docker__architecture_map[ansible_architecture] }}\n  signed-by=/etc/apt/keyrings/docker.asc]\n  {{ docker__apt_repository_url }}\n  {{ ansible_distribution_release }} {{ docker__channel | join(' ') }}\n```\n\n### Installing Python packages with Virtualenv and PIP\n\n#### Configuring Virtualenv\n\nRather than pollute your server's version of Python, all PIP packages are\ninstalled into a Virtualenv of your choosing.\n\n```yml\ndocker__pip_virtualenv: \"/usr/local/lib/docker/virtualenv\"\n```\n\n#### Installing PIP and its dependencies\n\nThis role installs PIP because Docker Compose v1 is installed with the\n`docker-compose` PIP package and Ansible's `docker_*` modules use the `docker`\nPIP package.\n\n```yml\ndocker__pip_dependencies:\n  - \"gcc\"\n  - \"python3-setuptools\"\n  - \"python3-dev\"\n  - \"python3-pip\"\n  - \"virtualenv\"\n```\n\n#### Installing PIP packages\n\n```yml\ndocker__default_pip_packages:\n  - name: \"docker\"\n    state: \"{{ docker__pip_docker_state }}\"\n  - name: \"docker-compose\"\n    version: \"{{ docker__compose_version }}\"\n    path: \"/usr/local/bin/docker-compose\"\n    src: \"{{ docker__pip_virtualenv + '/bin/docker-compose' }}\"\n    state: \"{{ docker__pip_docker_compose_state }}\"\n\n# Add your own PIP packages with the same properties as above.\ndocker__pip_packages: []\n```\n\n*Properties prefixed with \\* are required.*\n\n- *`name` is the package name\n- `version` is the package version to be installed (or \"\" if this is not defined)\n- `path` is the destination path of the symlink\n- `src` is the source path to be symlinked\n- `state` defaults to \"present\", other values can be \"forcereinstall\" or \"absent\"\n\n##### PIP package state\n\n- When set to `\"present\"`, the package will be installed but not updated on\nfuture runs\n- When set to `\"forcereinstall\"`, the package will always be (re)installed and\nupdated on future runs\n- When set to `\"absent\"`, the package will be skipped or removed\n\n```yml\ndocker__pip_docker_state: \"present\"\ndocker__pip_docker_compose_state: \"absent\"\n```\n\n#### Working with Ansible's `docker_*` modules\n\nThis role uses `docker_login` to login to a Docker registry, but you may also\nuse the other `docker_*` modules in your own roles. They are not going to work\nunless you instruct Ansible to use this role's Virtualenv.\n\nAt either the inventory, playbook or task level you'll need to set\n`ansible_python_interpreter: \"/usr/local/bin/python3-docker\"`. This works\nbecause this role creates a proxy script from the Virtualenv's Python binary to\n`python3-docker`.\n\nYou can look at this role's `docker_login` task as an example on how to do it\nat the task level.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickjj%2Fansible-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickjj%2Fansible-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickjj%2Fansible-docker/lists"}