Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/professormanhattan/ansible-docker

👀 Installs Docker on nearly any platform
https://github.com/professormanhattan/ansible-docker

ansible compose containers docker install installdoc installdoctor macos mblabs megabytelabs molecule orchestration professormanhattan role server system ubuntu washingtondc web windows

Last synced: 20 days ago
JSON representation

👀 Installs Docker on nearly any platform

Host: GitHub
URL: https://github.com/professormanhattan/ansible-docker
Owner: ProfessorManhattan
License: other
Created: 2022-02-24T01:06:12.000Z (almost 3 years ago)
Default Branch: master
Last Pushed: 2023-03-23T13:06:29.000Z (almost 2 years ago)
Last Synced: 2024-05-02T03:24:14.766Z (8 months ago)
Topics: ansible, compose, containers, docker, install, installdoc, installdoctor, macos, mblabs, megabytelabs, molecule, orchestration, professormanhattan, role, server, system, ubuntu, washingtondc, web, windows
Language: Shell
Homepage: https://megabyte.space
Size: 5.31 MB
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: docs/CODEOWNERS

Awesome Lists containing this project

Docker Ansible Role

An Ansible role that installs Docker on nearly any platform

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Quick Start](#quick-start)
- [Variables](#variables)
- [Variable Examples](#variable-examples)
- [`docker_edition`](#docker_edition)
- [`docker_users`](#docker_users)
- [Supported Operating Systems](#supported-operating-systems)
- [Dependencies](#dependencies)
- [Python](#python)
- [Galaxy Roles](#galaxy-roles)
- [Galaxy Collections](#galaxy-collections)
- [Example Playbook](#example-playbook)
- [Real World Example](#real-world-example)
- [Contributing](#contributing)
- [Affiliates](#affiliates)
- [TODO](#todo)
- [License](#license)

## Overview

This repository is the home of an [Ansible](https://www.ansible.com/) role that installs Docker on nearly any platform. [Docker](https://www.docker.com/) is a set of platform-as-a-service products that use OS-level virtualization to deliver software in packages called containers. Containers are isolated from one another and bundle their own software, libraries and configuration files; they can communicate with each other through well-defined channels.

## Features

**Installs docker-compose:**

- Both Mac OS X and Windows install Docker Desktop which includes Docker Compose as well as Notary, Kubernetes, and Credential Helper.
- Installs docker-compose if the `docker_install_compose` variable is set to true. docker-compose allows you to configure Docker containers in groups.

**Ensures Docker is installed:**

- Installs Docker on the target machine.
- Ensures Docker is started on boot.
- If the target Docker host is a Linux machine and the `docker_snap_install` variable is set to true, then Docker will be installed as a snap package.

**Adds specified users to docker group:**

- If the variable `docker_users` is set to an array of usernames then those users will be added to the docker group which allows them access to Docker.

**Generates TLS certificates:**

- Generates TLS/HTTPS certificates so that the Docker host can be controlled remotely. This is useful if you are using a centralized method of controlling all of your Docker hosts (like Portainer). This step only runs if the `docker_tls` variable is set to true.
- The certificates required for connecting to the Docker host are copied to the Ansible host's `~/.docker` folder.

## Quick Start

Looking to install Docker without having to deal with [Ansible](https://www.ansible.com/)? Simply run the following command that correlates to your operating system:

**Linux/macOS:**

```shell
curl -sS https://install.doctor/docker | bash
```

**Windows:**

```powershell
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://install.doctor/docker?os=win'))
```

**Important Note:** _Before running the commands above you should probably directly access the URL to make sure the code is legit. We already know it is safe but, before running any script on your computer, you should inspect it._

You can also check out **[Install Doctor](https://install.doctor)**. It is an app we created that can install any Ansible role with a one-liner. It has some other nifty features too like the ability to install binaries on-the-fly without requiring a password. However, if you would like to incorporate this role into an Ansible playbook (and customize settings) then please continue reading below.

## Variables

This role contains variables that you can customize. The variables you can customize are located in `defaults/main.yml`. By default, the variables use sensible defaults but you may want to customize the role depending on your use case. The variables, along with descriptions, are listed below:

| Name
| -------------------
| Docker
| docker_apt_arch
| docker_apt_gpg_key
| docker_apt_ignore_key_error
| docker_apt_release_channel
| docker_apt_repository
| docker_compose_path
| [`docker_edition`](
| docker_install_compose
| docker_no_plugins
| docker_package
| docker_restart_handler_state
| docker_snap_install
| docker_tls
| docker_tls_country
| docker_tls_division
| docker_tls_fqdn
| docker_tls_locality
| docker_tls_organization
| docker_tls_state
| [`docker_users`](#docker_users)
| docker_yum_gpg_key
| docker_yum_repo_url
| https_repository_prefix | Default Value | Description | ---------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Heyooo` | | | `amd64` | The processor architecture to use (Debian/Ubuntu only) | | `"https://download.docker.com/linux/{{ ansible_distribution \| lower }}/gpg"` | The URL of the apt repository's GPG key (Debian/Ubuntu only) | | `true` | Whether or not to ignore errors when adding the apt repository's GPG key (Debian/Ubuntu only) | | `stable` | The release channel to use on Debian/Ubuntu. You can set the value of this variable to either `stable` or `edge`. | | `See defaults/main.yml` | The apt repository to use (Debian/Ubuntu only) | | `/usr/local/bin/docker | compose`- The target destination of the`docker-compose` binary that will be installed | #docker_edition) | `ce` | Edition can be either `ce` (Community Edition) or `ee` (Enterprise Edition). | | `true` | Whether or not to install `docker-compose` | | `false` | Should the below Docker plugins be installed? Fast container image distribution plugin with lazy pulling - https://github.com/containerd/stargz-snapshotter A Docker volume plugin, managing persistent container volumes - https://github.com/rancher/convoy Docker Client Plugins Manager - build new plugins, publish them on Docker Hub - https://github.com/lukaszlach/clip | | `docker | {{ docker_edition }}` - The name of the Docker package to install | | `restarted` | The state that the Docker service should assume when a restart event is triggered | | `false` | Whether or not to use snap to install Docker - you can use this if there are issues with your configuration. Certificates (used by Portainer, for instance) will not be generated for a snap install. More information about the certificates is detailed below. | | `true` | When set to true, the role will configure Docker for TLS network connections and generate the required certificates. The certificates will be stored in `/etc/ssl/docker` on the client and in the `~/.docker` folder on the host. To reiterate, after each client machine installs Docker and generates certificates, the certificates are copied to the Ansible host machine. You can then use these certificates to connect to Docker daemons remotely (with Portainer, for instance). | | `US` | The country to use when configuring TLS | | `Megabyte Labs` | The division to use when configuring TLS | | `{{ fqdn \| default('machine.example.com') }}` | The FQDN to use when configuring TLS - this should be set to the FQDN of the Docker host that's being configured | | `The Hood` | The locality to use when configuring TLS | | `Megabyte LLC` | The organization to use when configuring TLS | | `New Jersey` | The state to use when configuring TLS | | `[]` | A list of users to add to the docker group | | `https://download.docker.com/linux/centos/gpg` | The URL of the GPG key to validate against when downloading from the specified yum repository | | `See defaults/main.yml` | The yum repository URL to retrieve the installation packages (CentOS/Fedora/RedHat only) | | `https://` | Allows you to customize what the apt repository URL starts with. This is useful if you are using something like apt-cacher-ng as a proxy cache which requires the URL to start with http://HTTPS/. (Debian/Ubuntu only) |

### Variable Examples

#### `docker_edition`

```yaml
#💬 Example implementation of the docker_edition variable
docker_edition:
- subitem: string
- subitem2: string
```

#### `docker_users`

```yaml
#💬 Example implementation of the docker_users variable
docker_users:
- `ansible_user`
- secondaryuser
- serviceaccount
```

## Supported Operating Systems

The chart below shows the operating systems that we have tested this role on. It is automatically generated using the Ansible Molecule tests located in the `molecule/` folder. There is CI logic in place to automatically handle the testing of Windows, macOS, Ubuntu, Fedora, CentOS, Debian, and Archlinux. If your operating system is not listed but is a variant of one of the systems we test (i.e. a Debian-flavored system or a RedHat-flavored system) then it is possible that the role will still work.

| OS Family | OS Version | Status | Idempotent | Tested On |
| --------- | ---------- | ------ | ---------- | --------- |

**_What does idempotent mean?_** Idempotent means that if you run this role twice in row then there will be no changes to the system the second time around.

We spent a lot of time perfecting our CI configurations and build tools. If you are interested in learning more about how we perfected our process then you might find our [Ansible common files](https://gitlab.com/megabyte-labs/common/ansible) and [Ansible documentation](https://gitlab.com/megabyte-labs/documentation/ansible) repositories interesting. See the [CONTRIBUTING.md](docs/CONTRIBUTING.md) guide for more details.

## Dependencies

Most of our roles rely on [Ansible Galaxy](https://galaxy.ansible.com) collections. Some of our projects are also dependent on other roles and collections that are published on Ansible Galaxy. Before you run this role, you will need to install the collection and role dependencies, as well as the Python requirements, by running:

```yaml
if type poetry &> /dev/null; then poetry install --no-root; else pip3 install -r .config/assets/requirements.txt; fi
ansible-galaxy install -r requirements.yml
```

Alternatively, you can simply run `bash .config/scripts/start.sh` if you are new to Ansible and do not mind the development requirements also being installed. This is the easy way of making sure that everything works properly.

### Python

Although the only tool necessary to run this play on a standard machine is Ansible (a Python package), we include several other Python dependencies that are required for specialized use cases and development. The table below details these packages:

| Package | Description | Required |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| ansible | A configuration management system that can remotely configure computers |

✔️

|
| docker | Enables the capability of provisioning Docker containers with Ansible |

✔️

|
| python-vagrant | Required for provisioning Vagrant VMs |

✔️

|
| pywinrm | Required for provisioning Windows machines that are using WinRM |

✔️

|
| ansible-lint | Linting tool for Ansible files | |
| ansibler | Custom tool used to generate advanced documentation (e.g. it generates the compatibility chart and some other charts) | |
| black | Python file auto-formatter included in case project utilizes Python test scripts | |
| blocklint | Linting tool that prevents certain words from entering the code base | |
| flake8 | Python linter that reports Python syntax and style errors | |
| mod-ansible-autodoc | Custom fork of [ansible-autodoc](https://pypi.org/project/ansible-autodoc/0.5.1.1/) which allows us to auto-generate documentation based on comments in the role's YAML files | |
| molecule | Test framework for Ansible | |
| molecule-docker | Molecule plugin for provisioning Docker containers | |
| molecule-vagrant | Molecule plugin for provisioning Vagrant VMs | |
| pre-commit-hooks | Suite of tools useful for linting | |
| proselint | Linter used to generate English-language improvements (used to improve documentation) | |
| yamllint | Linter for YAML files that ensures proper syntax and styling is used | |

### Galaxy Roles

Although most of our roles do not have dependencies, there are some cases where another role has to be installed before the logic can continue. At the beginning of the play, the Ansible Galaxy role dependencies listed in `meta/main.yml` will run. These dependencies are configured to only run once per playbook. If you include more than one of our roles in your playbook that have dependencies in common then the dependency installation will be skipped after the first run. Some of our roles also utilize helper roles directly from the task files which helps keep our [main playbook (Gas Station)](repository.playbooks) DRY.

The `requirements.yml` file contains a full list of the Ansible Galaxy dependencies required by this role (i.e. `meta/main.yml` role dependencies, helper roles, collections, etc.). For your convenience, a list of the role dependencies along with quick descriptions is below:

role_dependencies

### Galaxy Collections

This role is dependent on multiple Ansible Galaxy collections. The collections along with a links to their source are listed below.

-
-
-

## Example Playbook

With the dependencies installed, all you have to do is add the role to your main playbook. The role handles the `become` behavior so you can simply add the role to your playbook without having to worry about commands that should not be run as root:

```lang-yml
- hosts: all
roles:
- professormanhattan.docker
```

If you are incorporating this role into a pre-existing playbook, then it might be prudent to copy the requirements outlined in `pyproject.toml` and `requirements.yml` to their corresponding files in the root of your playbook so you only have to worry about installing one set of requirements during future use. Note that the dependencies in `pyproject.toml` can be moved to the more traditional `requirements.txt`, if that is what you are currently using to track Python dependencies.

### Real World Example

You can find an example of a playbook that incorporates this role in our main playbook (a.k.a. [Gas Station](https://github.com/ProfessorManhattan/Gas-Station)). The playbook is an excellent example for someone learning how to use Ansible. It also incorporates a lot of well-thought out build tools that more advanced Ansible users can appreciate. And people who could care less about Ansible can also benefit from it because it allows you to more or less turn your computer (and network) into the ultimate development enivornment. The bottom line is that it is an awesome project that developers should know about!

## Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://github.com/megabyte-labs/ansible-docker/issues). If you would like to contribute, please take a look at the [contributing guide](https://github.com/megabyte-labs/ansible-docker/blob/master/docs/CONTRIBUTING.md).

Sponsorship

Dear Awesome Person,

I create open source projects out of love. Although I have a job, shelter, and as much fast food as I can handle, it would still be pretty cool to be appreciated by the community for something I have spent a lot of time and money on. Please consider sponsoring me! Who knows? Maybe I will be able to quit my job and publish open source full time.

Sincerely,

**_Brian Zalewski_**