mirror of
https://gitea.elkins.co/Networking/ccl.git
synced 2025-02-04 12:02:47 -06:00
Add some meat onto README.md
This commit is contained in:
parent
84c431c8d4
commit
74e9edefdc
147
README.md
147
README.md
@ -1,15 +1,154 @@
|
||||
# ccl
|
||||
|
||||
A tool to manage a set of podman containers.
|
||||
A tool to manage a set of [podman][] containers, with a basic configuration
|
||||
defined in a common [toml][] file.
|
||||
|
||||
## Usage
|
||||
## Installation
|
||||
|
||||
Refer to `ccl help`
|
||||
```shell
|
||||
$ go install gitea.elkins.co/Networking/ccl@latest
|
||||
$ <editor> /etc/ccl.toml
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `/etc/ccl.toml`
|
||||
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.
|
||||
|
||||
<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.
|
||||
|
||||
## 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 |
|
||||
| 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/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user