4 releases (1 stable)
|1.3.0||Jan 4, 2022|
|0.1.2||Dec 28, 2021|
|0.1.1||Dec 27, 2021|
|0.1.0||Dec 27, 2021|
#1297 in Command line utilities
docker abstraction layer with added flair
This tool started its life as a way to make developing multiple smaller projects/apis that need to interact with each other a lot easier by allowing each project to define how it should be spun up as a container. Dare I say it's now possible to use it to somewhat orchestrate how smaller networks of services work. For when you don't need the scalability of Kubernetes I guess.
What it is
The gist of it all is that instead if having a big
docker-compose.yml full of services,
you have multiple smaller files spread out throughout your projects.
Big compose files become unwieldy pretty quick while dependencies between services increase. Carbon aims to somewhat alleviate that by giving each service responsibility over itself instead of a centralized file.
How it works
Carbon needs a
.envfile to function properly. That's where you define where all your mini-projects are located. If working in an organization, all projects within that organization are (hopefully) in the same directory. That's the directory you tell Carbon to look into by setting the
PROJECTS_DIRECTORYenvironment variable. If using a
.envfile, all of those variables will also be provided to the
carbon.ymlfiles (read below to find out about those). You can add a
.envfile to Carbon using the
carbon env add <file_path> <alias>command.
Each service has the right to define a
carbon.ymlfile within its directory. This file is allowed to contain exactly what would have been written in the
service:block for a normal
docker-compose.ymlfile. This carbon file tells Carbon how to spin up said service.
Each service is also allowed to define a
carbon-isotope.ymlfile within its directory. This file can be used to house a second type of configuration for the service. I, personally, have been using this to setup the exact same service, but with all of its ports exposed so that it can be used for development.
Once you've got your
.envfile ready, and one of your projects contains a
carbon.ymlfile, you can start that service with
carbon service start <service_name>. Keep in mind that Carbon will look at a directory named like the name you pass in. That's a current limitation: container names + directory names need to match up.
That's all the extra functionality that Carbon itself adds on top of docker compose. It does add some wrapper functionality to make using the docker cli a bit easier. Check the Overrides for that.
Docker things that carbon does as well, sometimes better.
- Commands return colored output/tables for a clearer understanding of what you're looking at.
- Carbon has a command for quickly starting a new service and immediately adding it to an existing docker network.
- Display information about networks
- Display information about containers
- Rebuild already running services on the fly. Useful when the image has been updated and it needs a hard reset. This does kill the service beforehand (for now at least).
- Easy management of environment variables
- Start services
- Stop services
- Create networks
- Remove networks
- Connect to networks
- ...and more
- Installation is done through
cargofor now since it does the job for my needs.
cargo install carbon-cli
- Also add an alias for your shell since it'll be called
carbonwas taken, nothing I can do about that.
Just make sure you have a
.local directory in your home folder. That's where Carbon will keep track of all the settings you choose while using it (in a file called
Here're some bits of information that might come in handy:
.envfiles can be used, since each file is given an alias when added it can also be set as active later on. List all your
carbon env ls. Carbon will always use the active
- Each subcommand of Carbon has an alias as well (usually the first letter of the original command).
listfor example has
rebuildcommands can all work on multiple services. You don't have to run the command multiple times, just once with everything. You can sort out the networks after the fact.
If something doesn't feel right when you really think it should, follow the checklist:
- Did you look at the proper usage of a command by adding the
carbon service -h.
- Have you read the (very basic (sorry)) explanation of how everything is supposed to work? (defined above)
- Rummage through the discussions and see if there is anything that might be related to your issue.
Emergency: If none of the above things help. Please start a discussion and tag a contributor. Don't jump directly to creating an issue since it might not really be an issue. Just poor documentation on our end, or just not an actual feature.
If you think a feature is broken, or should be implemented, or that there's a bug (unintended feature), talking about it is absolutely the best way of making sure that what you want actually happens. Unless you want to take things into your own hand and implement it yourself which is also more than fine.
Here's what you do:
- Start a discussion about it. Make sure to drag in all parties that seem relevant.
- Speak what's on your mind.
This is an actively maintained tool since I do use it constantly in my own projects, however unless I need a feature, I won't know that there's something missing so the best way to make something happen is to bring it up.
Keep in mind that commits relating to a fix should start with
fix: and commits
related to features should start with
feat:. This allows git-cliff to build a nice summary of what's happened every release.
If you're more of a visual person, here's some usage in the form of images:
- Help menu
- Listing all available containers/services
- Listing all available networks
- Starting a service called
- Stopping a service called hemingway