Process management using process-compose-flake

process-compose-flake is a flake-parts module for process-compose.

This flake-parts module allows you to declare one or more process-compose configurations using Nix attribute sets. It will generate corresponding packages that wrap the process-compose binary with the given configuration.

This module is practical for local development e.g. if you have a lot of runtime dependencies that depend on each other. Stop executing these programs imperatively over and over again in a specific order, and stop the need to write complicated shell scripts to automate this. process-compose gives you a process dashboard for monitoring, inspecting logs for each process, and much more, all of this in a TUI.

Quick Example

See example/flake.nix for an example flake. This example shows a demo of sqlite-web using the sample chinhook-database.

To run this example locally, 

mkdir example && cd example
nix flake init -t github:Platonic-Systems/process-compose-flake
nix run

This should open http://127.0.0.1:8213/ in your web browser. If not, navigate to the logs for the sqlite-web process and access the URL. Use demo as the password to access sqlite-web. The interface should look like this:

Usage

Let’s say you want to have a devShell that makes a command watch-server available, that you can use to spin up your projects backend-server, frontend-server, and proxy-server.

To achieve this using process-compose-flake you can simply add the following code to the perSystem function in your flake-parts flake. 

process-compose.watch-server = {
  settings.processes = {
    backend-server.command = "${self'.apps.backend-server.program} --port 9000";
    frontend-server.command = "${self'.apps.frontend-server.program} --port 9001";
    proxy-server.command =
      let
        proxyConfig = pkgs.writeTextFile {
          name = "proxy.conf";
          text = ''
            ...
          '';
        };
      in
      "${self'.apps.proxy-server.program} -c ${proxyConfig} -p 8000";
  };
};

process-compose-flake will generate the packages.${system}.watch-server output for you.

You can then spin up the processes by running nix run .#watch-server.

The package output in turn can be used to make the watch-server command available in your devShell: 

devShells = {
  default = pkgs.mkShell {
    name = "my-shell";
    nativeBuildInputs = [
      self'.packages.watch-server
    ];
  };
};

You can enter your devShell by running nix develop and run watch-server to run your processes.

preHook

If you’d like to run certain commands before starting the processes, you can add them to preHook: 

process-compose.watch-server = {
  preHook = ''
    # Cleanup on EXIT, this runs irrespective of exit-code of process-compose
    trap "rm -rf ./data" EXIT
    export USER=foo
  '';
};

postHook

Or if you’d like to run certain commands upon successful execution of process-compose, i.e exits with exit-code: 0, then add them to postHook: 

process-compose.watch-server = {
  postHook = ''
    cat foo.txt
  '';
};

Module API

Our submodule mirrors the process-compose YAML schema. A few things to remember:

  • process-compose.<name>.environment: In the YAML config, a list of environment strings are specified. While this is supported, you can also specify the env vars as a Nix attrset
  • process-compose.<name>.processes.<name>.command: The command string does not have access to the process environment, so if your command becomes shellscript-like you probably want to wrap it in a pkgs.writeShellApplication (see #22).
  • process-compose.<name>.shell: This is set to pkgs.bash by default, obviating reproducibility issues due to depending on globally available bash.

See also

Related projects

  • services-flake: NixOS-like services built on top of process-compose-flake. Use this if you want to run popular services (like postgres).
  • proc-flake: A similar module that uses a Procfile-based runner. It is less feature-rich, but at times more reliable than process-compose.
Links to this page