ccl/README.md

# ccl

A tool to manage a set of [podman][] containers, with a basic configuration
defined in a common [toml][] file.

## Installation

```shell
$ go install gitea.elkins.co/Networking/ccl@latest
$ <editor> /etc/ccl.toml
```

## Configuration

There are two arrays of objects that can be defined: Networks and Containers.
Currently, no global options are definable.

### Networks

Networks are used to set certain default values for containers that reference
them. The name of the network must match the name of a predefined podman
network. In my case (and one of the main reasons for this tool), I use macvlan
networks, which alters the network configuration somewhat, e.g.: the `ipv6` boolean
setting for the network is effectively ignored for macvlans. If there is a router
sending out RA's, the container will pick up on it and, depending on your podman
and host network settings, assign itself an autoconfigured ipv6 address, even when
you told podman to disable ipv6.

You can also set default DNS servers by network, so you don't have to tediously
do that for each container.

### Containers

A more complex object, but still cut down to a reasonable minimum. Basically
most of the information you would need if you typed `podman create ...` on the
command line, is defined in the `Container` structure. You can define one or
more networks, possibly overriding the configured defaults. The network name
must be a predefined podman network, but there actaully does not need to be
a `Network` configured for it in this file. Having the podman network defined
is enough. Refer to the example below for the fields available to be configured.

One field to point out is `Category`. Defining a category is optional, but
doing so allows you to do operations on multiple containers as a group (e.g.
starting, stopping, updating). This concept is distinct to `ccl` and is not
recognized or available to podman itself.

Two Categories are treated specially:

- `.` (*disabled*) indicates that containers identified here are to be excluded
  normally, unless specifically requested by name. This exclusion can be disabled
  (i.e. disabled containers included in the action) by specifying the `-a` option.

- `all` is an implicit category to match all containers (except disabled ones
  by default, as described above).

<details>
  <summary>Expand for example</summary>

```toml
[[networks]]
name = "mv2"
dns = ["10.2.0.54", "10.2.0.53"]
ipv6 = true # will allow accepting RAs if the host and podman also do (the default for macvlans)

[[networks]]
name = "mv6"
dns = ["10.6.0.54", "10.6.0.53"]
ipv6 = false # will define a sysctl to disable router advertisements on this interface

[[containers]]
category = "reg"
name = "plex"
hostname = "plex"
image = "docker.io/linuxserver/plex"
cdidevices = [ "nvidia.com/gpu=gpu0" ]
[containers.env]
VERSION = "latest"
TZ = "America/Chicago"
PUID = "996"
PGID = "996"
[[containers.mounts]]
source = "/media"
destination = "/media"
[[containers.mounts]]
source = "/config/plex"
destination = "/config"
[[containers.networks]]
name= "mv2"
ipv4_address = "10.2.1.14"
ipv6_address = "2001:db8:0:2::1:14"
[[containers.networks]]
name= "mv6"
ipv4_address = "10.6.1.14"
ipv6_address = "2001:db8:0:6::1:14"


[[containers]]
category = "reg"
name = "sabnzbd"
hostname = "sabnzbd"
image = "docker.io/linuxserver/sabnzbd"
[containers.env]
PUID = "3010"
PGID = "2130"
TZ = "America/Chicago"
[[containers.mounts]]
source = "/media"
destination = "/media"
[[containers.mounts]]
source = "/config/sabnzbd"
destination = "/config"
[[containers.networks]]
name= "mv2"
ipv4_address = "10.2.1.15"
ipv6_address = "2001:db8:0:2::1:15"
[[containers.networks]]
name= "mv6"
ipv4_address = "10.6.1.15"
ipv6_address = "2001:db8:0:6::1:15"
```
</details>

### Shell completion

This tool uses the [cobra](https://github.com/spf13/cobra) library, which
provides a convenient completion configurator for various shells. Refer to the
[cobra documentation](https://github.com/spf13/cobra/blob/main/shell_completions.md)
for info on how to use this feature.

## Usage

The following commands are available. All commands accept a list of container
names or categories. The tool will take the distinct set of defined containers
intersecting the command arguments, and iterate the verb over each of them. If
no arguments are provided, it is the same as "all". Invalid (unmatched)
container names are silently ignored.

| Command/Verb | Description                                                                            |
|--------------|----------------------------------------------------------------------------------------|
| create       | Create the configured containers                                                       |
| ls           | List some basic info about the containers                                              |
| show         | Output a [toml][] formatted configuration                                              |
| start        | Start containers. Do nothing for any container already running                         |
| restart      | Stop then start containers                                                             |
| update       | Pull updated images, tear down the configured container, and recreate it               |
| pull         | Just pull the configured image. Defined containers unaffected                          |
| recreate     | Stop, tear down, create, and restart containers (does not pull unless image not found) |
| rm           | Same as `podman rm --force`                                                            |
| stop         | Stop containers                                                                        |
| completion   | Generate a completion script for fish, zsh, or bash                                    |

Refer to `ccl help` for more info.

## Author

Joel D. Elkins <joel@elkins.com>

## License

[MIT](./LICENSE)

[toml]: https://toml.io/
[podman]: https://podman.io/