Update readme, and documentation folder

Signed-off-by: Dan Webb <dan.webb@damacus.io>
sous-chefs · Dec 11, 2024 · a676c21 · a676c21
1 parent ce56554
commit a676c21
Show file tree

Hide file tree

Showing 9 changed files with 525 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update documentation for `docker_container` resource
 - Update documentation for `docker_service` resource
 - Update documentation for `docker_exec` resource
+- Update resources overview
+- Update documentation for `docker_installation_package` resource
+- Update documentation for `docker_installation_script` resource
+- Update documentation for `docker_installation_tarball` resource
+- Update documentation for `docker_service_manager_execute` resource
+- Update documentation for `docker_service_manager_systemd` resource
+- Update documentation for `docker_volume_prune` resource
 
 ## 11.8.2 - *2024-12-11*
 

diff --git a/README.md b/README.md
@@ -73,19 +73,21 @@ Those recipes are found at `test/cookbooks/docker_test`.
 ## Resources Overview
 
 - [docker_service](documentation/docker_service.md): composite resource that uses docker_installation and docker_service_manager
-- [docker_installation](#docker_installation): automatically select an installation method
-- [docker_service_manager](#docker_service_manager): automatically selects a service manager
-- [docker_installation_script](#docker_installation_script): curl | bash
-- [docker_installation_package](#docker_installation_package): package 'docker-ce'
-- [docker_service_manager_execute](#docker_service_manager_execute): manage docker daemon with Chef
-- [docker_service_manager_systemd](#docker_service_manager_systemd): manage docker daemon with systemd unit files
-- [docker_image](documentation/docker_image.md): image/repository operations
 - [docker_container](documentation/docker_container.md): container operations
-- [docker_tag](documentation/docker_tag.md): image tagging operations
-- [docker_registry](documentation/docker_registry.md): registry operations
+- [docker_exec](documentation/docker_exec.md): execute commands inside running containers
+- [docker_image](documentation/docker_image.md): image/repository operations
+- [docker_image_prune](documentation/docker_image_prune.md): remove unused docker images
+- [docker_installation_package](documentation/docker_installation_package.md): install Docker via package 'docker-ce'
+- [docker_installation_script](documentation/docker_installation_script.md): install Docker via curl | bash
+- [docker_installation_tarball](documentation/docker_installation_tarball.md): install Docker from a tarball
 - [docker_network](documentation/docker_network.md): network operations
-- [docker_volume](documentation/docker_volume.md): volume operations
 - [docker_plugin](documentation/docker_plugin.md): plugin operations
+- [docker_registry](documentation/docker_registry.md): registry operations
+- [docker_service_manager_execute](documentation/docker_service_manager_execute.md): manage docker daemon with Chef
+- [docker_service_manager_systemd](documentation/docker_service_manager_systemd.md): manage docker daemon with systemd unit files
+- [docker_tag](documentation/docker_tag.md): image tagging operations
+- [docker_volume](documentation/docker_volume.md): volume operations
+- [docker_volume_prune](documentation/docker_volume_prune.md): remove unused docker volumes
 
 ## Getting Started
 

diff --git a/documentation/docker_installation_package.md b/documentation/docker_installation_package.md
@@ -0,0 +1,94 @@
+# docker_installation_package
+
+The `docker_installation_package` resource is responsible for installing Docker via package manager. It supports both Debian/Ubuntu and RHEL/Fedora platforms.
+
+## Actions
+
+- `:create` - Installs Docker package and sets up the Docker repository if enabled
+- `:delete` - Removes the Docker package
+
+## Properties
+
+| Property          | Type    | Default                | Description                                                |
+|------------------|---------|------------------------|------------------------------------------------------------|
+| `setup_docker_repo` | Boolean | `true`                | Whether to set up the Docker repository                    |
+| `repo_channel`    | String  | `'stable'`            | Repository channel to use (`stable`, `test`, `nightly`)    |
+| `package_name`    | String  | `'docker-ce'`         | Name of the Docker package to install                      |
+| `package_version` | String  | `nil`                 | Specific package version to install                        |
+| `version`         | String  | `nil`                 | Docker version to install (e.g., '20.10.23')              |
+| `package_options` | String  | `nil`                 | Additional options to pass to the package manager          |
+| `site_url`        | String  | `'download.docker.com'`| Docker repository URL                                     |
+
+## Examples
+
+### Install Latest Version of Docker
+
+```ruby
+docker_installation_package 'default' do
+  action :create
+end
+```
+
+### Install Specific Version of Docker
+
+```ruby
+docker_installation_package 'default' do
+  version '20.10.23'
+  action :create
+end
+```
+
+### Install from Test Channel
+
+```ruby
+docker_installation_package 'default' do
+  repo_channel 'test'
+  action :create
+end
+```
+
+### Install Without Setting Up Docker Repository
+
+```ruby
+docker_installation_package 'default' do
+  setup_docker_repo false
+  action :create
+end
+```
+
+### Remove Docker Installation
+
+```ruby
+docker_installation_package 'default' do
+  action :delete
+end
+```
+
+## Platform Support
+
+This resource supports the following platforms:
+
+### Debian/Ubuntu
+
+- Debian 9 (Stretch)
+- Debian 10 (Buster)
+- Debian 11 (Bullseye)
+- Debian 12 (Bookworm)
+- Ubuntu 18.04 (Bionic)
+- Ubuntu 20.04 (Focal)
+- Ubuntu 22.04 (Jammy)
+- Ubuntu 24.04 (Noble)
+
+### RHEL/Fedora
+
+- RHEL/CentOS 7 and later
+- Fedora (latest versions)
+
+## Notes
+
+- The resource automatically handles architecture-specific package names and repositories
+- For Debian/Ubuntu systems, it installs `apt-transport-https` package as a prerequisite
+- Version strings are handled differently based on the Docker version and platform:
+  - For versions < 18.06: Uses format like `VERSION~ce-0~debian` or `VERSION~ce-0~ubuntu`
+  - For versions >= 18.09: Uses format like `5:VERSION~3-0~debian-CODENAME` or `5:VERSION~3-0~ubuntu-CODENAME`
+  - For versions >= 23.0 on Ubuntu: Uses format like `5:VERSION-1~ubuntu.VERSION~CODENAME`
diff --git a/documentation/docker_installation_script.md b/documentation/docker_installation_script.md
@@ -0,0 +1,76 @@
+# docker_installation_script
+
+The `docker_installation_script` resource installs Docker on Linux systems using the official Docker installation scripts. This is also known as the "curl pipe bash" installation method.
+
+## Actions
+
+- `:create` - Downloads and executes the Docker installation script
+- `:delete` - Removes Docker packages installed by the script
+
+## Properties
+
+| Property     | Type   | Default        | Description                                                           |
+|-------------|--------|----------------|-----------------------------------------------------------------------|
+| `repo`      | String | `'main'`       | Repository to use for installation. One of: `main`, `test`, or `experimental` |
+| `script_url`| String | Based on repo  | URL of the installation script. Defaults to official Docker URLs based on the repo property |
+
+## Examples
+
+### Install Docker from Main Repository
+
+```ruby
+docker_installation_script 'default' do
+  action :create
+end
+```
+
+### Install Docker from Test Repository
+
+```ruby
+docker_installation_script 'default' do
+  repo 'test'
+  action :create
+end
+```
+
+### Install Docker from Experimental Repository
+
+```ruby
+docker_installation_script 'default' do
+  repo 'experimental'
+  action :create
+end
+```
+
+### Install Docker Using Custom Script URL
+
+```ruby
+docker_installation_script 'default' do
+  script_url 'https://my-custom-docker-install.example.com/install.sh'
+  action :create
+end
+```
+
+### Remove Docker Installation
+
+```ruby
+docker_installation_script 'default' do
+  action :delete
+end
+```
+
+## Notes
+
+- This resource is only available on Linux systems
+- The installation script requires `curl` to be installed (the resource will install it if missing)
+- The script is executed with `sh` shell
+- The installation is considered complete when `/usr/bin/docker` exists
+- When removing Docker, both `docker-ce` and `docker-engine` packages are removed
+- Default script URLs:
+  - Main: <https://get.docker.com/>
+  - Test: <https://test.docker.com/>
+  - Experimental: <https://experimental.docker.com/>
+
+## Platform Support
+
+This resource is supported on all Linux platforms that can run the Docker installation scripts.
diff --git a/documentation/docker_installation_tarball.md b/documentation/docker_installation_tarball.md
@@ -0,0 +1,84 @@
+# docker_installation_tarball
+
+The `docker_installation_tarball` resource installs Docker on a system using pre-compiled binary tarballs from the official Docker downloads.
+
+## Actions
+
+- `:create` - Downloads and installs Docker from a tarball
+- `:delete` - Removes Docker installed from a tarball
+
+## Properties
+
+| Property    | Type   | Default           | Description                                |
+|------------|--------|-------------------|--------------------------------------------|
+| `checksum`  | String | Based on version  | SHA256 checksum of the Docker tarball     |
+| `source`    | String | Based on version  | URL of the Docker tarball                 |
+| `channel`   | String | `'stable'`        | Docker release channel to use             |
+| `version`   | String | `'20.10.11'`      | Docker version to install                 |
+
+## Examples
+
+### Install Default Version
+
+```ruby
+docker_installation_tarball 'default' do
+  action :create
+end
+```
+
+### Install Specific Version
+
+```ruby
+docker_installation_tarball 'default' do
+  version '19.03.15'
+  action :create
+end
+```
+
+### Install from Custom Source
+
+```ruby
+docker_installation_tarball 'default' do
+  source 'https://example.com/docker-20.10.11.tgz'
+  checksum 'dd6ff72df1edfd61ae55feaa4aadb88634161f0aa06dbaaf291d1be594099ff3'
+  action :create
+end
+```
+
+### Remove Docker Installation
+
+```ruby
+docker_installation_tarball 'default' do
+  action :delete
+end
+```
+
+## Platform Support
+
+This resource supports the following platforms:
+
+### Linux
+
+- Version 18.03.1: checksum `0e245c42de8a21799ab11179a4fce43b494ce173a8a2d6567ea6825d6c5265aa`
+- Version 18.06.3: checksum `346f9394393ee8db5f8bd1e229ee9d90e5b36931bdd754308b2ae68884dd6822`
+- Version 18.09.9: checksum `82a362af7689038c51573e0fd0554da8703f0d06f4dfe95dd5bda5acf0ae45fb`
+- Version 19.03.15: checksum `5504d190eef37355231325c176686d51ade6e0cabe2da526d561a38d8611506f`
+- Version 20.10.11: checksum `dd6ff72df1edfd61ae55feaa4aadb88634161f0aa06dbaaf291d1be594099ff3`
+
+### Darwin (macOS)
+
+- Version 18.03.1: checksum `bbfb9c599a4fdb45523496c2ead191056ff43d6be90cf0e348421dd56bc3dcf0`
+- Version 18.06.3: checksum `f7347ef27db9a438b05b8f82cd4c017af5693fe26202d9b3babf750df3e05e0c`
+- Version 18.09.9: checksum `ed83a3d51fef2bbcdb19d091ff0690a233aed4bbb47d2f7860d377196e0143a0`
+- Version 19.03.15: checksum `61672045675798b2075d4790665b74336c03b6d6084036ef22720af60614e50d`
+- Version 20.10.11: checksum `8f338ba618438fa186d1fa4eae32376cca58f86df2b40b5027c193202fad2acf`
+
+## Notes
+
+- The resource automatically detects the system architecture and kernel type to download the appropriate tarball
+- Requires `tar` package to be installed (the resource will install it if missing)
+- Creates a `docker` system group
+- Filename format varies based on Docker version:
+  - For versions >= 19.x.x: `docker-VERSION.tgz`
+  - For version 18.09.x: `docker-VERSION.tgz`
+  - For versions <= 18.06.x: `docker-VERSION-ce.tgz`
diff --git a/documentation/docker_service.md b/documentation/docker_service.md
@@ -20,16 +20,19 @@ The service management strategy is automatically chosen based on the platform bu
 - `service_manager` - Service manager to use: `execute`, `systemd`, `none`, or `auto` (default)
 
 #### Script Installation
+
 - `repo` - Repository URL for script installation
 - `script_url` - Custom script URL for installation
 
 #### Package Installation
+
 - `package_version` - Specific package version to install
 - `package_name` - Package name (default: docker-ce)
 - `setup_docker_repo` - Whether to configure Docker repository
 - `package_options` - Additional package installation options
 
 #### Tarball Installation
+
 - `checksum` - SHA256 checksum of Docker binary
 - `docker_bin` - Path to Docker binary
 - `source` - URL to Docker binary tarball
@@ -118,6 +121,7 @@ The service management strategy is automatically chosen based on the platform bu
 ### Service Management
 
 #### Systemd Options
+
 - `systemd_opts` - Additional systemd service unit options
 - `systemd_socket_opts` - Additional systemd socket unit options
 - `mount_flags` - Systemd mount propagation flags