Skip to content

Commit

Permalink
Update readme, and documentation folder
Browse files Browse the repository at this point in the history
Signed-off-by: Dan Webb <dan.webb@damacus.io>
  • Loading branch information
damacus committed Dec 11, 2024
1 parent ce56554 commit 2c28faf
Show file tree
Hide file tree
Showing 10 changed files with 524 additions and 13 deletions.
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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*

Expand Down
22 changes: 12 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
94 changes: 94 additions & 0 deletions documentation/docker_installation_package.md
Original file line number Diff line number Diff line change
@@ -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`
75 changes: 75 additions & 0 deletions documentation/docker_installation_script.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# 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/>

## Platform Support

This resource is supported on all Linux platforms that can run the Docker installation scripts.
84 changes: 84 additions & 0 deletions documentation/docker_installation_tarball.md
Original file line number Diff line number Diff line change
@@ -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`
4 changes: 4 additions & 0 deletions documentation/docker_service.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 2c28faf

Please sign in to comment.