add docs for new install command feature (#342)

* add docs for new install command feature

* format

* Update docs/reference/components/applications.md

Co-authored-by: Dawson Toth <[email protected]>

* Update docs/reference/components/applications.md

Co-authored-by: Dawson Toth <[email protected]>

* Update docs/reference/components/applications.md

Co-authored-by: Kris Zyp <[email protected]>

---------

Co-authored-by: Dawson Toth <[email protected]>
Co-authored-by: Kris Zyp <[email protected]>

Author: 3 people

docs/developers/operations-api/components.md

@@ -6,12 +6,15 @@ title: Components
 
 ## Add Component
 
-Creates a new component project in the component root directory using a predefined template.
+Creates a new component project in the component root directory using a specified template (defaults to the [application template](https://github.com/HarperFast/application-template)).
 
 _Operation is restricted to super_user roles only_
 
 - `operation` _(required)_ - must always be `add_component`
 - `project` _(required)_ - the name of the project you wish to create
+- `template` _(optional)_ - the URL of a git repository to use as a template. Must be a string. Defaults to `https://github.com/HarperFast/application-template`
+- `install_command` _(optional)_ - A command to use when installing the component. Must be a string. Defaults to `npm install`. Depending on the host environment, you can use this to switch to using an alternative package manager.
+- `install_timeout` _(optional)_ - The maximum time, in milliseconds, to wait for the install command to complete. Must be a number. Defaults to `300000` (5 minutes)
 - `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean.
 
 ### Body
@@ -81,7 +84,8 @@ _Operation is restricted to super_user roles only_
 - `payload` _(optional)_ - a base64-encoded string representation of the .tar file. Must be a string
 - `restart` _(optional)_ - must be either a boolean or the string `rolling`. If set to `rolling`, a rolling restart will be triggered after the component is deployed, meaning that each node in the cluster will be sequentially restarted (waiting for the last restart to start the next). If set to `true`, the restart will not be rolling, all nodes will be restarted in parallel. If `replicated` is `true`, the restart operations will be replicated across the cluster.
 - `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean.
-- `install_command` _(optional)_ - A command to use when installing the component. Must be a string. This can be used to install dependencies with pnpm or yarn, for example, like: `"install_command": "npm install -g pnpm && pnpm install"`
+- `install_command` _(optional)_ - A command to use when installing the component. Must be a string. Defaults to `npm install`. Depending on the host environment, you can use this to switch to using an alternative package manager.
+- `install_timeout` _(optional)_ - The maximum time, in milliseconds, to wait for the install command to complete. Must be a number. Defaults to `300000` (5 minutes)
 
 ### Body
 

docs/reference/components/applications.md

@@ -120,6 +120,43 @@ These `package` values are all supported because behind-the-scenes, Harper is ge
 
 Finally, don't forget to include `restart=true`, or run `harperdb restart target=<remote>`.
 
+## Dependency Management
+
+Naturally, applications may have dependencies. Since we operate on top of Node.js, we default to leveraging `npm` and `package.json` for dependency management.
+
+As already covered, there are a number of ways to run an application on Harper. From symlinking to a local directory, to deploying it via the `deploy_component` operation. Harper does its best to seamlessly run your application.
+
+During application loading, if an application directory contains a `node_modules` directory or it excludes a `package.json`, Harper will skip dependency installation. Otherwise, Harper will check the application's config (values specified in the `harperdb-config.yaml` file) for `install: { command, timeout }` fields (see the example below for more information). If it exists, Harper will use the specified command to install dependencies. If not, then Harper will attempt to derive the package manager from the [`package.json#devEngines#packageManager`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#devengines) field (which can specify an npm alternate like yarn or pnpm). Finally, if no package manager or install command could be derived, Harper will default to using `npm install`.
+
+The Application operations [`add_component`](../../developers/operations-api/components.md#add-component) and [`deploy_component`](../../developers/operations-api/components.md#deploy-component) support customizing the install command (and timeout) through the `install_command` and `install_timeout` fields.
+
+If you plan to use an alternative package manager than `npm`, ensure it is installed and configured on the host machine. Harper does not currently support the `"onFail": "download"` option in `package.json#devEngines#packageManager` and will fallback to `"onFail": "error"` behavior.
+
+### Example `harperdb-config.yaml`
+
+```yaml
+myApp:
+  package: ./my-app
+  install:
+    command: yarn install
+    timeout: 600000 # 10 minutes
+```
+
+### Example `package.json`
+
+```json
+{
+	"name": "my-app",
+	"version": "1.0.0",
+	"devEngines": {
+		"packageManager": {
+			"name": "pnpm",
+			"onFail": "error"
+		}
+	}
+}
+```
+
 ## Advanced
 
 The following methods are advanced and should be executed with caution as they can have unintended side-effects. Always backup any critical Harper instances before continuing.