Configuration
Platformatic Runtime is configured with a configuration file. It supports the use of environment variables as setting values with environment variable placeholders.
Configuration Files
The Platformatic CLI automatically detects and loads configuration files found in the current working directory with the file names listed here.
Alternatively, you can use the --config option to specify a configuration file path for most wattpm CLI commands. The configuration examples in this reference use the JSON format.
Supported File Formats
For detailed information on supported file formats and extensions, please visit our Supported File Formats and Extensions page.
Settings
Configuration settings containing sensitive data should be set using environment variable placeholders.
The autoload and applications settings can be used together, but at least one
of them must be provided. When the configuration file is parsed, autoload
configuration is translated into applications configuration.
autoload
The autoload configuration is intended to be used with monorepo applications.
autoload is an object with the following settings:
path(required,string) - The path to a directory containing the applications to load. In a traditional monorepo application, this directory is typically namedpackages.exclude(arrayofstrings) - Child directories insidepaththat should not be processed.mappings(object) - Each applicaiton is given an ID and is expected to have a Platformatic configuration file. By default, the ID is the application's directory name, and the configuration file is expected to be a well-known Platformatic configuration file.mappingscan be used to override these default values. Supported properties are the same of entries inapplication, exceptpath,url, andgitBranch.
preload
The preload configuration is intended to be used to register
Application Performance Monitoring (APM) agents. preload should contain
a path or a list of paths pointing to a CommonJS or ES module that is loaded at the start of
the app worker thread.
applications
applications is an array of objects that defines the applications managed by the
runtime. Each application object supports the following settings:
-
id(required,string) - A unique identifier for the application. -
path(required,string) - The path to the directory containing the application. It can be omitted ifurlis provided. -
url(required,string) - The URL of the application remote GIT repository, if it is a remote application. It can be omitted ifpathis provided. You can specify a branch using the URL fragment syntax:https://github.com/user/repo.git#branch-name. -
gitBranch(string) - The branch of the application to resolve. Takes precedence over the branch specified in the URL fragment. -
config(string) - The configuration file used to start the application. -
useHttp(boolean) - The application will be started on a random HTTP port on127.0.0.1, and exposed to the other applications via that port, on default it is set tofalse. Set it totrueif you are using @fastify/express. -
reuseTcpPorts: Enable the use of thereusePortoption whenever any TCP server starts listening on a port. The default istrue. The values specified here overrides the values specified in the runtime. -
workers- The number of workers to start for this application. If the application is the entrypoint or if the runtime is running in development mode this value is ignored and hardcoded to1. This can be specified as:number- A fixed number of workersobject- Advanced worker configuration with the following properties:static(number) - A fixed number of workersdynamic(boolean) - Enable dynamic worker scaling. This is only meaningful when set tofalseto disable dynamic scaling for this application.minimum(number) - Minimum number of workers when using dynamic scalingmaximum(number) - Maximum number of workers when using dynamic scaling
-
health(object): Configures the health check for each worker of the application. It supports all the properties also supported in the runtime health property. The values specified here overrides the values specified in the runtime. -
arguments(arrayofstrings) - The arguments to pass to the application. They will be available inprocess.argv. -
envfile(string) - The path to an.envfile to load for the application. By default, the.envfile is loaded from the application directory. -
env(object) - An object containing environment variables to set for the application. Values set here takes precedence over values set in theenvfile. -
sourceMaps(boolean) - Iftrue, source maps are enabled for the application. Default:false. -
packageManager(string) - The package manager to use when using theinstall-dependenciesor theresolvecommands ofwattpm-utils. Default is to autodetect it, unless it is specified via command line. -
preload(stringorarrayofstrings): A file or a list of files to load before the application code. -
nodeOptions(string): TheNODE_OPTIONSto apply to the application. These options are appended to any existing option. -
permissions(object): Configure application-level security permissions to restrict file system access. Supported properties are:fs:read(arrayofstrings): Array of file system paths the application is permitted to read from. Uses the same syntax as Node.js --allow-fs-read.write(arrayofstrings): Array of file system paths the application is permitted to write to. Uses the same syntax as Node.js --allow-fs-write.
When filesystem permissions are enabled, certain paths are automatically added to maintain application functionality:
- The current Watt project's
node_modulesdirectory - The application's own
node_modulesdirectory - Any
node_modulesdirectories found in parent directories of the runtime path
The security permissions are based on Node.js permission model and therefore the application will have restricted access to native modules, child processes, worker threads, the inspector protocol, and WASI. See the Node.js Permission Model Constraints for complete details.
-
dependencies(arrayofstrings): A list of applications that must be started before attempting to start the current application. Note that the runtime will not perform any attempt to detect or solve dependencies cycles. -
telemetry(object): containing aninstrumentationsarray to optionally configure additional open telemetry intrumentations per application, e.g.:
"applications": [
{
"id": "api",
"path": "./services/api",
"telemetry": {
"instrumentations": ["@opentelemetry/instrumentation-express"]
}
}
]
It's possible to specify the name of the export of the instrumentation and/or the options:
"applications": [
{
"id": "api",
"path": "./services/api",
"telemetry": {
"instrumentations": [{
"package": "@opentelemetry/instrumentation-express",
"exportName": "ExpressInstrumentation",
"options": {}
}]
}
}
]
An alias for applications. If both are present, their content will be merged.
It's also possible to disable the instrumentation by setting the enabled value property to false (env variables are also supported):
"applications": [
{
"id": "api",
"path": "./services/api",
"telemetry": {
"enabled": "false",
"instrumentations": [{
"package": "@opentelemetry/instrumentation-express",
}]
}
}
]
env
An object containing environment variables to set for all applications in the
runtime. Any environment variables set in the env object will be merged with
the environment variables set in the envfile and env properties of each
application, with application-level environment variables taking precedence.
sourceMaps
If true, source maps are enabled for all applications. Default: false. This setting can be overridden at the application level.
resolvedServicesBasePath
The base path, relative to the configuration file to store resolved applications. Each application will be saved in {resolvedServicesBasePath}/{id}. Default: external.
entrypoint
The Platformatic Runtime's entrypoint is an applicaiton that is exposed
publicly. This value must be the ID of an application defined via the autoload or
applications configuration.
workers
Configures the default number of workers to start per each application. Some values can be overridden at the application level.
This can be specified as:
number- A fixed number of workers (minimum 1)object- Advanced worker configuration with the following properties:static(number) - A fixed number of workersdynamic(boolean) - Enable dynamic worker scaling (default:false). The dynamic worker scaler automatically adjusts the number of workers for each application based on Event Loop Utilization (ELU) and available system memory. It can be overridden at the application level.minimum(number) - The minimum number of workers that can be used for each application. Default:1.maximum(number) - The maximum number of workers that can be used for each application. Default: globaltotalvalue.total(number) - The maximum number of workers that can be used for all applications. Default:os.availableParallelism()(typically the number of CPU cores).maxMemory(number) - The maximum total memory in bytes that can be used by all workers. Default: 90% of the system's total memory.cooldown(number) - The amount of milliseconds the scaling algorithm will wait after making a change before scaling up or down again. This prevents rapid oscillations. Default:20000.gracePeriod(number) - The amount of milliseconds after a worker is started before the scaling algorithm will start collecting metrics for it. This allows workers to stabilize after startup. Default:30000.
This value is hardcoded to 1 if the runtime is running in development mode or when applying it to the entrypoint.
workersRestartDelay
Configures the amount of milliseconds to wait before replacing another worker of an application during a restart.
gracefulShutdown
Configures the amount of milliseconds to wait before forcefully killing an application or the runtime.
The object supports the following settings:
application(number) - The graceful shutdown timeout for an application.runtime(number) - The graceful shutdown timeout for the entire runtime.
For both the settings the default is 10000 (ten seconds).
watch
An optional boolean, set to default false, indicating if hot reloading should
be enabled for the runtime. If this value is set to false, it will disable
hot reloading for any applications managed by the runtime. If this value is
true, then hot reloading for individual applications is managed by the
configuration of that application.
Note that watch should be enabled for each individual application in the runtime.
While hot reloading is useful for development, it is not recommended for use in production.
startTimeout
The number of milliseconds to wait before considering an application as failed to start. Default: 30000.
restartOnError
The number of milliseconds to wait before attempting to restart an application that unexpectedly exit.
If not specified or set to true, the default value is 5000, set to 0 or false to disable.
Any value smaller than 10 will cause immediate restart of the application.
This setting is ignored in production, where applications are always restarted immediately.
exitOnUnhandledErrors
When enabled (default), Platformatic automatically installs error handlers for uncaughtException and unhandledRejection events on each worker process. These handlers will automatically restart the affected worker when such errors occur.
Setting this to false disables the automatic error handling, making you responsible for implementing proper error handling in your application code.
health
Configures the health check for each worker. This is enabled only if restartOnError is greater than zero.
The object supports the following settings:
enabled(boolean): If to enable the health check. Default:true.interval(number): The interval between checks in milliseconds. Default:30000.gracePeriod(number): How long after the application started before starting to perform health checks. Default:30000.maxUnhealthyChecks(number): The number of consecutive failed checks before killing the worker. Default:10.maxELU(number): The maximum allowed Event Loop Utilization. The value must be a percentage between0and1. Default:0.99.maxHeapUsed(number): The maximum allowed memory utilization. The value must be a percentage between0and1. Default:0.99.maxHeapTotal(numberorstring): The maximum allowed memory allocatable by the process. The value must be an amount in bytes, in bytes or in memory units. Default:4GB.maxYoungGeneration(numberorstring): The maximum amount of memory that can be used by the young generation. The value must be an amount in bytes, in bytes or in memory units. Default:128MBcodeRangeSize(numberorstring): The maximum amount of memory that can be used for code range (compiled code). The value must be an amount in bytes or in memory units. Default:268435456(256MB).
telemetry
Open Telemetry is optionally supported with these settings:
applicationName(required,string) — Name of the application as will be reported in open telemetry. In theruntimecase, the name of the applications as reported in traces is${applicationName}-${applicationId}, whereapplicationIdis the id of the application in the runtime.version(string) — Optional version (free form)skip(array). Optional list of operations to skip when exporting telemetry definedobjectwith properties:method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACEpath. e.g.:/documentation/json
exporter(objectorarray) — Exporter configuration. If not defined, the exporter defaults toconsole. If an array of objects is configured, every object must be a valid exporter object. The exporter object has the following properties:type(string) — Exporter type. Supported values areconsole,otlp,zipkinandmemory(default:console).memoryis only supported for testing purposes.options(object) — These options are supported:url(string) — The URL to send the telemetry to. Required forotlpexporter. This has no effect onconsoleandmemoryexporters.headers(object) — Optional headers to send with the telemetry. This has no effect onconsoleandmemoryexporters.