Super Orchestrator

The purpose of Super Orchestrator is to act as a more easliy programmable, scalable, and debuggable alternative to the horrors of bash scripts and docker-compose. This is based on Tokio and supplies convenient tools for file management, command running, and Docker container management.

First, see the documentation of stacked_errors (https://docs.rs/stacked_errors/latest/stacked_errors/) to understand the error strategy. Then, look over the documentation. Finally, check the examples in order of: paths, file_options, basic_commands, basic_containers, commands, dockerfile_entrypoint_pattern, postgres, and clean (note that some of these use UNIX specific commands that will not run successfully in some environments).

Notes

The "nix_support" feature enables some functions to be able to send UNIX signals to commands.

Cross compilation

Cross compilation on Windows is practically impossible (believe me, I have tried going down the rabbit hole twice, just use WSL 2 or MSYS2 instead). The dockerfile entrypoint pattern examples that use cross compilation will not work on straight Windows. However, it is possible in general to cross compile inside a container and still keep build artifacts for fast recompilation by voluming CARGO_HOME. An example of what this looks like is

if cfg!(windows) {
    Container::new(
            "builder",
            Dockerfile::contents(/* build container definition */),
        )
        .volume(
            home::cargo_home().stack()?.to_str().stack()?, // using the `home` crate
            "/root/.cargo", // if building in a typical Linux container
        )
        .volume(/* base directory */, "/needs_build")
        .workdir("/needs_build")
        .entrypoint_args(["sh", "-c", &format!("cargo -vV && {build_cmd}",)])
        .run(
            Some(/* dockerfiles_dir */),
            Duration::from_secs(3600),
            /* logs_dir */,
            true,
        )
        .await
        .stack()?
        .assert_success()
        .stack()?;
}

I would include functions to do this in super_orchestrator itself, but at this level we are just making too many environmental assumptions. If the cargo version used locally and in the build container are too incompatible, there may be problems. This ultimately must be automated per-repo and the dockerfile_entrypoint_pattern is just a starter example.

Docker inconsistencies

Docker is usually good with consistency and being able to run the same thing between different environments, but there are a few things that have different defaults (meaning something that runs perfectly on one environment may fail in another), most notably things involving network access.

• When enabling IPv6, you should use the arguments

container.create_args([
    "--cap-add=NET_ADMIN", // if doing anything requiring admin access for network stuff
    "--sysctl",
    "net.ipv6.conf.all.disable_ipv6=0", // some environments need this also
    "--sysctl",
    "net.ipv6.conf.default.disable_ipv6=0", // some environments need this also
    "--sysctl",
    "net.ipv6.conf.all.forwarding=1", // for packet forwarding if needed
])

• The "--internal" network argument does not have the intended effect on all platforms, even on some WSL 2 Linux distributions.