# Installer
[](https://github.com/SlimIO/Installer/commit-activity)
[](https://travis-ci.com/SlimIO/Installer)
[](https://greenkeeper.io/)
SlimIO Agent and Addons installer. We use this package in:
- the [CLI](https://github.com/SlimIO/CLI) to install and clone the agent and all addons.
- [Tcp-SDK](https://github.com/SlimIO/Tcp-Sdk) for testing the communication with the Socket addon.
This package has been designed to be used by Addons to achieve clean unit-testing (by re-cloning a complete agent).
## Requirements
- [Node.js](https://nodejs.org/en/) v12 or higher
## Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @slimio/installer
# or
$ yarn add @slimio/installer
```
## Usage example
Clone a SlimIO agent (what we do for example in the [Tcp-Sdk](https://github.com/SlimIO/Tcp-Sdk) test suite).
```js
const installer = require("@slimio/installer");
const treekill = require("tree-kill");
async function main() {
const agentDir = process.cwd();
await installer.initAgent(agentDir, { name: "agent" });
// Start the SlimIO Agent his child process
const cp = await installer.runAgent(agentDir, true);
try {
// Do your work here...
}
finally {
treekill(cp.pid);
}
}
main().catch(console.error);
```
Or install SlimIO Addons in a valid SlimIO Agent directory.
```js
const installer = require("@slimio/installer");
// CONSTANTS
const kAddonsToInstall = ["cpu", "MySQL"];
async function main() {
const agentDir = process.cwd();
await Promise.allSettled(
kAddonsToInstall.map((addonName) => installer.installAddon(addonName, agentDir))
);
}
main().catch(console.error);
```
## API
initAgent(location: string, options?: InitOptions): Promise< string >
This method will extract and install all required (built-in) addons for a SlimIO Agent.
```ts
interface InitOptions {
token?: string;
name?: string;
forceClean?: boolean;
}
```
By default `forceClean` is equal to true (this mean that the code will try to remove any agent on the system!).
runAgent(location: string, silent?: boolean, options?: object): Promise< NodeJS.ReadStream >
Run a given SlimIO Agent in a dedicated Node.js child process. Return the process Read Stream.
installDependencies(cwd?: string, lock?: boolean): Promise< void >
Install the dependencies of a given Node.js project directory (it spawn a Node.js process to run the npm install / npm ci command). This command only install **production** dependencies (devDependencies are ignored).
The current working dir value is `process.cwd()`.
renameDirFromManifest(dir?: string, fileName?: string): Promise< string >
Found the real addon name in the SlimIO manifest file and rename the directory name (because by default the directory name is the one from github which is a bad thing). This method is automatically used in **installAddon**.
By default value of the **fileName** argument is `slimio.toml`. The current working dir value is `process.cwd()`.
extractAgent(dest: string, options?: ExtractOptions): Promise< string >
Download the Agent archive on github (or extract a recent version stored in cache for performance). This method is used by **initAgent**.
```ts
interface ExtractOptions {
downloadFromRemote?: boolean;
token?: string;
name?: string;
}
```
By default **downloadFromRemote** is equal to **true**.
installAddon(addonExpr: string, dest: string, options?: InstallOptions): Promise< string >
Install one Addon at the given destination (which must be a valid SlimIO Agent path).
```ts
interface InstallOptions {
installDependencies?: boolean;
searchInRegistry?: boolean;
token?: string;
}
```
By default the dependencies of the addon will be installed. The **searchInRegistry** default value is **false**.
```js
await installAddon("SlimIO.Socket", "./myAgent");
await installAddon("YourGithubOrg.AddonName", "./myAgent");
await installAddon("Alerting", "./myAgent"); // Same as SlimIO.Alerting
await installAddon("https://github.com/SlimIO/Aggregator", "./myAgent");
```
parseAddonExpr(addonExpr: URL | string): ExprResult
Parse an Addon installation expression. The function try to guess the Organization and the Repository name by itself, if there is no org then it will return **SlimIO** as the default org. The returned payload is described by the following TypeScript interface:
```ts
interface ExprResult {
repoUserOrg: string;
repoName: string;
host: null | string;
}
```
Current supported host are `github.com` and `gitlab.com`.
```js
parseAddonExpr("https://github.com/SlimIO/Socket"); // { repoUserOrg: "SlimIO", repoName: "Socket", host: "github.com" }
parseAddonExpr("Socket"); // { repoUserOrg: "SlimIO", repoName: "Socket", host: null }
parseAddonExpr("Foo/Socket"); // { repoUserOrg: "Foo", repoName: "Socket", host: null }
```
setRegistryURL(url: URL): void
Configure the default registry URL used under the hood by the Registry SDK package.