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 |
#2552 in Command line utilities
395KB
1.5K
SLoC
docker abstraction layer with added flair
Fast travel:
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
.env
file 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 thePROJECTS_DIRECTORY
environment variable. If using a.env
file, all of those variables will also be provided to thecarbon.yml
files (read below to find out about those). You can add a.env
file to Carbon using thecarbon env add <file_path> <alias>
command. -
Each service has the right to define a
carbon.yml
file within its directory. This file is allowed to contain exactly what would have been written in theservice:
block for a normaldocker-compose.yml
file. This carbon file tells Carbon how to spin up said service. -
Each service is also allowed to define a
carbon-isotope.yml
file 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
.env
file ready, and one of your projects contains acarbon.yml
file, you can start that service withcarbon 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.
Overrides
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
Installing
- Installation is done through
cargo
for 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
carbon-cli
otherwise. Justcarbon
was 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 carbon-footprint.yml
)
Tips
Here're some bits of information that might come in handy:
- Multiple
.env
files can be used, since each file is given an alias when added it can also be set as active later on. List all your.env
files withcarbon env ls
. Carbon will always use the active.env
file. - Each subcommand of Carbon has an alias as well (usually the first letter of the original command).
list
for example hasls
. - Service
start
,stop
,add
, andrebuild
commands 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.
Getting help
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
-h
flag? Example: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.
Contributing
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.
Images
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
hemingway
- Stopping a service called hemingway
Dependencies
~3.5–4.5MB
~83K SLoC