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_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: