Build tool for custom configuration of multiple smaller services, and wrapper commands for docker containers to make your life easier.
MPL-2.0 License
carbon.yml
in your repository rootcarbon.yml
in the repositories.That's the gist of it. A script with nice output that basically concatenates small, chunked, docker compose service definitions into a big file and runs them.
I don't know, honestly. Maybe you have multiple small docker services that are all defined in the same compose file but you'd like them to be separated into their own configuration files within each project. Maybe you're just here for the helpers, that's a valid reason too.
I just built this because I needed it and it's now public because I thought other people might want to use it too.
Apart from that, this provides:
co2 shell <container-name> | iex
(powershell).co2 exec <container-A> <container-B> <container-C> -c echo "Hello World"
.co2 show -r
for a fresh table of all running containers).Read more about the commands at the Documentation Section
Simplest way to install it at the moment is using homebrew:
$ brew tap 0x20F/carbon
$ brew install carbon
The binary is still compiled for a bunch of platforms and provided neatly in each of the releases. So if homebrew isn't your cup of tea(??) you can always download other binaries directly from there until other options become available.
There are plans to allow installing through different linux package managers, and maybe even windows, just haven't gotten around to it yet.
Wanna complain? That's fine. Here's how:
If you're not sure how to find something you're looking for, here are a few things you can try:
-h
flag.Note: This program does have helpful wrapper commands for common docker things, however, it's not just that. Therefore it also contains more features that you may or may not choose to use.
Double Note: Keep in mind that all these options also exist in the program help menu which can be accessed by passing the
-h
param to any command or subcommand.
Triple Note: If you see the π¦ next to something, it's carbon specific and you probably shouldn't care if docker is all you want.
Let's start then. Here are all the command wrappers (and commands related to unique carbon functionality) so far and what they do:
carbon.yml
The carbon.yml
file is the heart and soul of all carbon specific functionality within the program.
This is just a simple declaration of the docker-compose kind, without any of the docker compose bits added.
Note: Any valid docker compose field is valid in this file
Looks kind of like this:
my-service:
image: golang
ports:
- "80:80"
volumes:
- /some/path:/another/path
command: tail -f /dev/null
That's pretty simple right?
Now to run that service:
A
, and the parent B
(/B/A
), you register B
not A
. This allows for a single store registrationco2 service start my-service
Pro Tip: If you ever want more than one service defined in your file, you separate them using the yaml document separator
---
In carbon, there's a concept called a store. This is, in simple terms, a directory in which carbon can look for carbon.yml
files. Each store can have its own
.env
file linked to it and it will pass it to all the services that are found within that store. The store commands described below
make it pretty clear how to make use of a store.
co2 show
This one handles multiple things depending on the set flag:
-r
Will show all the running docker containers.-a
Will show all the carbon.yml
service files that are available for use.-s
Shows all the stores that carbon has access toPro Tip: These can all be used together
co2 logs
Shows the logs for one or multiple containers. Flags are as follows:
-f
if provided, will not exit the command after output but will keep listening for logs.Pro Tip: You specify the Keys you get from the show command as parameters
co2 shell
This one will build a docker command that gets you a shell into whatever container or service you specified. Do keep in mind, however, that since this only returns the composed command you still have to run it somehow. Example:
$ co2 shell my-container
$ docker exec -it my-container /bin/bash
Pro Tip: You can use the unique IDs that the show command displays to quickly specify a container
-sh
To get /bin/sh
instead of bash
-c
To execute a custom shell (or command if you really wanna) as in co2 shell -c /bin/but-something-else my-container
co2 store add
This will add a new directory(store) for carbon to look in when searching for carbon.yml
files. It comes packed with 2 whole parameters:
-s
The path for the store, could be absolute (/home/whatever/you
) or relative (../../../sure
)-i
A unique ID for the store you're adding. If not provided, one will be generated automatically so don't worry.-e
A path to an environment file (of the .env
variety). This will be passed along to all the service configurations in the given store when they start.# Example Usage
$ co2 store add -s ../ -i unique-store
Pro Tip: You can list all the stores with the show command
co2 store remove
The opposite of add as you'd expect. All it takes is that unique ID that you maybe defined, but definitely got with the add
command.
$ co2 store remove unique-store
Pro Tip: The remove command can take any number of store IDs
co2 start
Looks through all the registered stores (see add on how to register stores) and starts all of the provided services if they're found.
As an added bonus, if the service defines any other services it is dependent on, usually within the depends_on
field in the configuration, it will make sure that
those services are included in the provided list otherwise it'll abort and inform you that you're missing some important things.
Example:
$ co2 service start A B C
Note: The names you provide here are what you defined within your carbon.yml file
If some of the provided services are already running but you'd like to stop them all and force a refresh, there's a flag for that:
-f
forces a service start, meaning all provided services will be stopped before attempting to start them again.co2 stop
Looks through the currently running carbon services and stops the provided ones.
Example:
$ co2 service stop A B C
Note: The names you provide here are what you defined within your carbon.yml file