process-compose-flake/README.md

process-compose-flake

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

Alternatives

For a similar (and less feature-rich) module that uses a Procfile-based runner, see https://github.com/srid/proc-flake

Contributing

Please run ./test.sh on a NixOS machine to run the full suite of tests before pushing changes to the main branch. Our CI (Github Actions) cannot do this yet.