Build tool for custom setups of docker containers. Docker compose didn't offer enough, Kubernetes offered too much. Carbon is the in-between.

Overview

banner

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

  1. 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 the PROJECTS_DIRECTORY environment variable. If using a .env file, all of those variables will also be provided to the carbon.yml files (read below to find out about those). You can add a .env file to Carbon using the carbon env add <file_path> <alias> command.

  2. 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 the service: block for a normal docker-compose.yml file. This carbon file tells Carbon how to spin up said service.

  3. 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.

  4. Once you've got your .env file ready, and one of your projects contains a carbon.yml file, 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.


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

  1. Installation is done through cargo for now since it does the job for my needs.
cargo install carbon-cli
  1. Also add an alias for your shell since it'll be called carbon-cli otherwise. Just carbon 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 with carbon 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 has ls.
  • Service start, stop, add, and rebuild 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:

  1. Did you look at the proper usage of a command by adding the -h flag? Example: carbon service -h.
  2. Have you read the (very basic (sorry)) explanation of how everything is supposed to work? (defined above)
  3. 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:

  1. Start a discussion about it. Make sure to drag in all parties that seem relevant.
  2. 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

banner

  • Listing all available containers/services

banner

  • Listing all available networks

banner

  • Starting a service called hemingway

banner

  • Stopping a service called hemingway

banner

Comments
  • Allow for descriptor files for development

    Allow for descriptor files for development

    Besides the carbon.yml file in each service, there can be a carbon-isotope.yml file that contains the descriptions of that exact same service but for development.

    Maybe different port mappings, volumes, images, whatever.

    • Carbon will then have to read the isotope file it it's being told.
    • Maybe if all service names that start with c- should be run from the isotope file. Like c-artemis for example.
    opened by 0x20F 1
  • Testable refactor

    Testable refactor

    • Removes the intermediary service command
    • Adds a heap load of tests, and a bunch of abstractions too to make it work, sadly...
    • Polished functionality and removed some bugs (whatever the tests discovered)
    • Proper refactor, no more massive and scary looking methods. Just small and scary looking...
    opened by 0x20F 0
  • Golang

    Golang

    Rewrite the whooooooooole thing in go.

    • Better structure
    • Better performance, not because Rust was slow, because I wrote bad code...
    • More reliable since all the important bits are actually tested now
    • Prettier output, somewhat...
    opened by 0x20F 0
  • Output created compose file

    Output created compose file

    A subcommand to output the docker-compose file that is built out of all the specified services to a specific path. This is useful if that compose file needs to later be given to a docker swarm deploy or something similar.

    Something like: co2 save ./

    • [x] Subcommand for telling the application that we just want the output
    • [x] Subcommand value should be the path to output to
    • [x] Fully expand path so it gets saved where it should
    • [x] Don't add anything extra to the generated compose file (like container names and so on), just straight up copy pasting...
    • [x] Save into the provided path, whether its a file or not, the user's job to be specific.
    opened by 0x20F 0
  • README Update

    README Update

    It's good to have a file describing everything this package can do as well as what it's actually meant for. Whether it goes public or not, it's nice to have.

    opened by 0x20F 0
  • Speed up network list command

    Speed up network list command

    • Run the network inspect command with all containers at once instead of separate.
    • Allow serde to parse into a Vec of Network objects so the trimming doesn't have to happen.
    opened by 0x20F 0
  • Parameter for adding dotenv file

    Parameter for adding dotenv file

    • [x] Provide a way to set env file by number
    • [x] Move the current foothold file to ~/.local/carbon-foothold.toml
    • [x] Create a new file in /tmp/carbon-emissions.toml and store the running services in there. This'll be the session database
    • [x] Provide a way to show indexed env files in a numbered list
    • [x] Provide a way to add new env file paths, if parameter isn't provided, check current directory for it and add it to the config as active
    • [x] Whenever commands are run, use the active env file as a starting point, unless override parameter is provided
    • [x] If parameterr with new env file is provided, add it to the list and set as active
    opened by 0x20F 0
  • Show networks

    Show networks

    Pull in serde, for starters since the docker CLI has a command that returns information about a network as json.

    Use that to dynamically build a nice summary of all networks.

    opened by 0x20F 0
  • Stop command for services

    Stop command for services

    Do the opposite of start.

    • this will require keeping track of what services are part of what compose files
    • which in turn will mean keeping track of each compose file
    opened by 0x20F 0
Releases(v1.1.2)
Owner
akhara
APIs and services for running and maintaining complex operations on massive amounts of data. Text summarization, mathematical and sentiment predictions, etc.
akhara
Docker containers on a synthetic network. Run applications in a context that lets you manipulate their network conditions.

Synthetic Network Docker containers on a synthetic network. Run applications in a context that lets you manipulate their network conditions. Dependenc

Daily 58 Dec 15, 2022
Bioyino is a distributed statsd-protocol server with carbon backend.

Bioyino The StatsD server written in Rust Description Bioyino is a distributed statsd-protocol server with carbon backend. Features all basic metric t

avito.tech 206 Dec 13, 2022
Rust client for Kubernetes

Rust client for Kubernetes API.

null 244 Dec 17, 2022
A tool for defining and running multi-container Docker applications

Ikki Ikki is a tool for defining and running multi-container Docker applications. It is similar to Docker Compose but comes with some differences. Goa

Kirill Vasiltsov 39 Dec 21, 2022
wireguard tool to manage / generate configuration. Maintain one yaml configuration file to quickly build wireguard network.

wgx wireguard tool to manage / generate configuration. Maintain one yaml configuration file to quickly build wireguard network. Usage wgx --h USAGE:

yinheli 6 Nov 3, 2022
Docker daemon API in Rust

Bollard: an asynchronous rust client library for the docker API Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API cont

Niel Drummond 439 Jan 3, 2023
Implementation of the Docker Registry HTTP API V2 in Rust, that can act as a proxy to other registries

Docker registry server and proxy (I'm bad at creating catchy names, but this one is good enough.) This project aims to implement a Docker Registry HTT

l4p1n (Mathias B.) 2 Dec 30, 2022
It's like "docker stats" but with beautiful, real-time charts into your terminal. 📊

?? ds - Real-time Stats with Terminal Charts Visualize container stats with beautiful, real-time charts directly in your terminal. Why ds? Missing Cha

Rafael R. Camargo 5 Oct 3, 2023
Easily share data between terminal windows!

abra A tool that makes data sharing between terminal windows easy. abra can be used for displaying info about the current working directory, for split

Denis Isidoro 23 Oct 2, 2022
Simple project to test grpc between ruby (client) and rust (server)

grpc-example Simple project to test grpc between ruby (client) and rust (server). Usage To simplify a lot this project uses docker and docker compose

Bruno Arueira 2 Oct 14, 2021
Lightweight p2p library. Support build robust stable connection on p2p/distributed network.

Chamomile Build a robust stable connection on p2p network features Support build a robust stable connection between two peers on the p2p network. Supp

CympleTech 94 Jan 6, 2023
Volo is a high-performance and strong-extensibility Rust RPC framework that helps developers build microservices.

Volo is a high-performance and strong-extensibility Rust RPC framework that helps developers build microservices.

CloudWeGo 1.3k Jan 2, 2023
Immitate the documentation build that docs.rs would do

cargo docs-rs Run cargo rustdoc with the same options that would be used by docs.rs, taking into account the package.metadata.docs.rs configured in Ca

David Tolnay 12 Oct 1, 2023
A tool to aid in self-hosting. Expose local services on your computer, via a public IPv4 address.

innisfree A tool to aid in self-hosting. Expose local services on your computer, via a public IPv4 address. Why? Most of the data I maintain is local,

Conor Schaefer 7 Mar 19, 2022
Library + CLI-Tool to measure the TTFB (time to first byte) of HTTP requests. Additionally, this crate measures the times of DNS lookup, TCP connect and TLS handshake.

TTFB: CLI + Lib to Measure the TTFB of HTTP/1.1 Requests Similar to the network tab in Google Chrome or Mozilla Firefox, this crate helps you find the

Philipp Schuster 24 Dec 1, 2022
Passive TCP/IP fingerprinting tool

This tool analyzes first stage of TCP handshake (SYN) and recognize operating system of client Build To build sp0ky, you need to install Rust git clon

Ivan Tyunin 19 Sep 12, 2022
A fast, stable, efficient, and lightweight intranet penetration, port forwarding tool supports multiple connections, cascading proxy, and transmission encryption

A fast, stable, efficient, and lightweight intranet penetration, port forwarding tool supports multiple connections, cascading proxy, and transmission encryption

editso 1.3k Dec 30, 2022
Userspace libpcap-based tool to mirror your dns traffic

DNS traffic mirroring tool (dns-mirror) Description Userspace libpcap-based tool. dns-mirror sniffs dns packets on the given interface and proxies it

Timofey 1 Mar 15, 2022
A rust-based command line tool to serve as a gateway for a Internet Computer replica.

icx-proxy A command line tool to serve as a gateway for a Internet Computer replica. Contributing Please follow the guidelines in the CONTRIBUTING.md

DFINITY 25 Sep 6, 2022