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.keep-project
Pass --keep-project to process-compose
Type: boolean
Default:
false
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>.defaults.enable
Whether to enable default settings for processes in this configuration.
Type: boolean
Default:
true
Declared by:
perSystem.process-compose.<name>.defaults.processSettings
Default settings that will be applied to all processes in this configuration.
Individual process settings can override these defaults. When setting defaults,
use lib.mkDefault to ensure individual process settings take precedence.
Example:
defaults.processSettings = {
availability.restart = lib.mkDefault "on_failure";
availability.max_restarts = lib.mkDefault 3;
namespace = lib.mkDefault "myapp";
};
Type: module
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_daemonflag set totrue. - In case a process is daemon it will be considered running until stopped.
- Daemon processes can only be stopped with the
$PROCESSNAME.shutdown.commandas 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: