process-compose-flake

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.

See quick example to get started with process-compose-flake

Installation

To use these options, add to your flake inputs:

process-compose-flake.url = "github:Platonic-Systems/process-compose-flake";

and inside the mkFlake:

imports = [
  inputs.process-compose-flake.flakeModule
];

Run nix flake lock and you're set.

Options

perSystem.process-compose

process-compose-flake: creates process-compose executables from process-compose configurations written as Nix attribute sets.

Type: attribute set of (submodule)

Declared by:

perSystem.process-compose.<name>.package

The process-compose package to bundle up in the command package and flake app.

Type: package

Default: pkgs.process-compose

Declared by:

perSystem.process-compose.<name>.cli.environment

Environment variables to pass to process-compose binary.

Type: submodule

Default: { }

Declared by:

perSystem.process-compose.<name>.cli.environment.PC_DISABLE_TUI

Disable the TUI (Text User Interface) of process-compose

Type: null or boolean

Default: null

Declared by:

perSystem.process-compose.<name>.cli.options

CLI options to pass to process-compose binary

Type: submodule

Default: { }

Declared by:

perSystem.process-compose.<name>.cli.options.log-file

Pass --log-file to process-compose

Type: null or string

Default: null

Declared by:

perSystem.process-compose.<name>.cli.options.no-server

Pass --no-server to process-compose

Type: boolean

Default: false

Declared by:

perSystem.process-compose.<name>.cli.options.ordered-shutdown

Pass --ordered-shutdown to process-compose

Type: boolean

Default: false

Declared by:

perSystem.process-compose.<name>.cli.options.port

Pass --port to process-compose

Type: null or signed integer

Default: null

Declared by:

perSystem.process-compose.<name>.cli.options.read-only

Pass --read-only to process-compose

Type: boolean

Default: false

Declared by:

perSystem.process-compose.<name>.cli.options.unix-socket

Pass --unix-socket to process-compose

Type: null or string

Default: null

Declared by:

perSystem.process-compose.<name>.cli.options.use-uds

Pass --use-uds to process-compose

Type: boolean

Default: false

Declared by:

perSystem.process-compose.<name>.cli.outputs.environment

Shell script prefix setting environment variables

Type: string (read only)

Default: ""

Declared by:

perSystem.process-compose.<name>.cli.outputs.options

The final CLI arguments we will pass to process-compose binary.

Type: string (read only)

Default: ""

Declared by:

perSystem.process-compose.<name>.cli.postHook

Shell commands to run after process-compose completes.

Type: strings concatenated with “\n”

Default: ""

Declared by:

perSystem.process-compose.<name>.cli.preHook

Shell commands to run before process-compose starts.

Type: strings concatenated with “\n”

Default: ""

Declared by:

perSystem.process-compose.<name>.outputs.package

The final package that will run ‘process-compose up’ for this configuration.

Type: package

Declared by:

perSystem.process-compose.<name>.outputs.check

Run the process-compose package with test process Enabled.

Note: This is meant to be run in CI.

Type: null or package

Default: null

Declared by:

perSystem.process-compose.<name>.outputs.testPackage

Like outputs.package but includes the “test” process

Set to null if there is no “test” process.

Type: null or package

Declared by:

perSystem.process-compose.<name>.settings

For each attribute x = process-compose config a flake app and package x is added to the flake. Which runs process-compose with the declared config.

Type: submodule

Default: { }

Example:

{
  watch-server = {
    processes = {
      backend = "${pkgs.simple-http-server}";
      frontend = "${pkgs.simple-http-server}";
    };
  };
};

Declared by:

perSystem.process-compose.<name>.settings.environment

Attrset of environment variables.

List of strings is also allowed.

Type: null or (list of string) or attribute set of string

Default: null

Example:

{
  ABC = "2221";
  PRINT_ERR = "111";
}

Declared by:

perSystem.process-compose.<name>.settings.log_length

Log length to display in TUI mode.

Type: null or (unsigned integer, meaning >=0)

Default: null

Example: 3000

Declared by:

perSystem.process-compose.<name>.settings.log_level

Level of logs to output.

Type: null or one of “trace”, “debug”, “info”, “warn”, “error”, “fatal”, “panic”

Default: null

Example: "info"

Declared by:

perSystem.process-compose.<name>.settings.log_location

File to write the logs to.

Type: null or string

Default: null

Example: "./pc.log"

Declared by:

perSystem.process-compose.<name>.settings.processes

A map of process names to their configuration.

Type: attribute set of (submodule)

Default: { }

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.availability.backoff_seconds

Restart will wait process.availability.backoff_seconds seconds between stop and start of the process. If not configured the default value is 1s.

Type: null or (unsigned integer, meaning >=0)

Default: null

Example: 2

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.availability.exit_on_end

Whether to gracefully stop all the processes upon the exit of the current process.

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.availability.exit_on_skipped

Whether to gracefully stop all the processes upon the process being skipped.

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.availability.max_restarts

Max. number of times to restart.

Tip: It might be sometimes useful to exit_on_end with restart: on_failure and max_restarts in case you want the process to recover from failure and only cause termination on success.

Type: null or (unsigned integer, meaning >=0)

Default: null

Example: 0

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.availability.restart

When to restart the process.

Type: null or one of “always”, “on_failure”, “exit_on_failure”, “no”

Default: null

Example: "on_failure"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.command

The command or script or package that runs this process

If a package is given, its executable is used as the command. Otherwise, the command string is wrapped in a pkgs.writeShellApplication which uses ShellCheck and runs the command in bash.

Type: package or string

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.depends_on

Process dependency relationships

Type: null or (attribute set of (submodule))

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.depends_on.<name>.condition

The condition the parent process must be in before starting the current one.

Type: one of “process_completed”, “process_completed_successfully”, “process_healthy”, “process_log_ready”, “process_started”

Example: "process_healthy"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.disable_ansi_colors

Whether to disable colors in the logs.

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.disabled

Whether the process is disabled. Useful when a process is required to be started only in a given scenario, like while running in CI.

Even if disabled, the process is still listed in the TUI and the REST client, and can be started manually when needed.

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.environment

Attrset of environment variables.

List of strings is also allowed.

Type: null or (list of string) or attribute set of string

Default: null

Example:

{
  ABC = "2221";
  PRINT_ERR = "111";
}

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.is_daemon

  • For processes that start services / daemons in the background, please use the is_daemon flag set to true.
  • In case a process is daemon it will be considered running until stopped.
  • Daemon processes can only be stopped with the $PROCESSNAME.shutdown.command as in the example above.

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.is_foreground

Foreground processes are useful for cases when a full tty access is required (e.g. vim, top, gdb -tui)

  • Foreground process have to be started manually (F7). They can be started multiple times.
  • They are available in TUI mode only.
  • To return to TUI, exit the foreground process.
  • In TUI mode, a local process will be started.

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.is_tty

Simulate TTY mode for this process

Type: null or boolean

Default: null

Example: true

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe

The settings used to check if the process is alive.

Type: null or (submodule)

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.exec

Execution settings.

Type: null or (submodule)

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.exec.command

The command to execute in order to check the health of the process.

Type: string

Example: "ps -ef | grep -v grep | grep my-proccess"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.failure_threshold

Number of times to fail before giving up on restarting the process.

Type: unsigned integer, meaning >=0

Default: 3

Example: 3

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.http_get

URL to determine the health of the process.

Type: null or (submodule)

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.http_get.host

The host address which process-compose uses to probe the process.

Type: string

Example: "google.com"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.http_get.path

The path to the healtcheck endpoint.

Type: string

Default: "/"

Example: "/"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.http_get.port

Which port to probe the process on.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Example: "8080"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.http_get.scheme

The protocol used to probe the process listening on host.

Type: string

Default: "http"

Example: "http"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.initial_delay_seconds

Wait for initial_delay_seconds before starting the probe/healthcheck.

Type: unsigned integer, meaning >=0

Default: 0

Example: 0

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.period_seconds

Check the health every period_seconds.

Type: unsigned integer, meaning >=0

Default: 10

Example: 10

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.success_threshold

Number of successful checks before marking the process Ready.

Type: unsigned integer, meaning >=0

Default: 1

Example: 1

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.liveness_probe.timeout_seconds

How long to wait for a given probe request.

Type: unsigned integer, meaning >=0

Default: 3

Example: 3

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.log_location

Log location of the process-compose process.

Type: null or string

Default: null

Example: "./pc.my-proccess.log"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.namespace

Used to group processes together.

Type: string

Default: "default"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe

The settings used to check if the process is ready to accept connections.

Type: null or (submodule)

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.exec

Execution settings.

Type: null or (submodule)

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.exec.command

The command to execute in order to check the health of the process.

Type: string

Example: "ps -ef | grep -v grep | grep my-proccess"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.failure_threshold

Number of times to fail before giving up on restarting the process.

Type: unsigned integer, meaning >=0

Default: 3

Example: 3

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.http_get

URL to determine the health of the process.

Type: null or (submodule)

Default: null

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.http_get.host

The host address which process-compose uses to probe the process.

Type: string

Example: "google.com"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.http_get.path

The path to the healtcheck endpoint.

Type: string

Default: "/"

Example: "/"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.http_get.port

Which port to probe the process on.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Example: "8080"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.http_get.scheme

The protocol used to probe the process listening on host.

Type: string

Default: "http"

Example: "http"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.initial_delay_seconds

Wait for initial_delay_seconds before starting the probe/healthcheck.

Type: unsigned integer, meaning >=0

Default: 0

Example: 0

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.period_seconds

Check the health every period_seconds.

Type: unsigned integer, meaning >=0

Default: 10

Example: 10

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.success_threshold

Number of successful checks before marking the process Ready.

Type: unsigned integer, meaning >=0

Default: 1

Example: 1

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.readiness_probe.timeout_seconds

How long to wait for a given probe request.

Type: unsigned integer, meaning >=0

Default: 3

Example: 3

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.ready_log_line

A string to search for in the output of the command that indicates the process is ready. String will be part of a regex ‘.{ready_log_line}.’. This should be used for long running processes that do not have a readily accessible check for http or similar other checks.

Type: null or string

Default: null

Example: "process is ready"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.shutdown.command

The command to run while process-compose is trying to gracefully shutdown the current process.

Note: The shutdown.command is executed with all the Environment Variables of the primary process

Type: null or string

Default: null

Example: "sleep 2 && pkill -f 'test_loop.bash my-proccess'"

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.shutdown.signal

If shutdown.command is not defined, exit the process with this signal. Defaults to 15 (SIGTERM)

Type: null or (unsigned integer, meaning >=0)

Default: null

Example: 15

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.shutdown.timeout_seconds

Wait for timeout_seconds for its completion (if not defined wait for 10 seconds). Upon timeout, SIGKILL is sent to the process.

Type: null or (unsigned integer, meaning >=0)

Default: null

Example: 10

Declared by:

perSystem.process-compose.<name>.settings.processes.<name>.working_dir

The directory to run the process in.

Type: null or string

Default: null

Example: "/tmp"

Declared by:

perSystem.process-compose.<name>.settings.shell.shell_argument

Arguments to pass to the shell given by shell_command.

Type: string

Default: "-c"

Example: "-c"

Declared by:

perSystem.process-compose.<name>.settings.shell.shell_command

The shell to use to run the process commands.

For reproducibility across systems, by default this uses pkgs.bash.

Type: string

Default: "lib.getExe pkgs.bash"

Declared by:

perSystem.process-compose.<name>.settings.version

Version of the process-compose configuration.

Type: null or string

Default: null

Example: "0.5"

Declared by: