How to create your own script repository?

You can add a custom script repository to the platform. A dedicated or virtual server can be used as a repository. A different set of scripts can be displayed for each interface language in the platform.

Adding a repository

To create a custom script repository, perform the following actions on the repository server and the platform server.

On the repository server:

Install and configure a web server.
Create a directory for the repository. The directory must be accessible for external HTTP connections. For example, /var/www/html/recipes/.
Copy the script files to the repository directory.
Create files with script descriptions in the repository directory:
- metadata_ru.json — for display in the Russian platform interface;
- metadata_en.json — for display in the English platform interface;
- metadata_es.json — for display in the Spanish platform interface;
- metadata.json — for display in any platform interface.
  
  You do not need to create all files. For example, if scripts must be displayed only in the Russian and English interfaces, create only the files metadata_ru.json and metadata_en.json.
  If the same set of scripts with the same descriptions must be displayed for all platform languages, create only the file metadata.json.

Fill in the metadata files.

Example metadata.json description file

{
  "type": "recipe",
  "recipe": [
    {
      "name": "ForLinux",
      "tags": [
        "linux"
      ],
      "description": "script1",
      "file_name": "script1.sh",
      "updated_at": "2020-05-15 12:01:12"
    },
    {
      "name": "ForWindows",
      "tags": [
        "windows"
      ],
      "description": "script2",
      "file_name": "script2.ps",
      "updated_at": "2022-04-14 07:57:13"
    }
  ]
}

File details

If necessary, add additional fields.
Example metadata.json file with additional fields
```
{
  "type": "recipe",
  "recipe": [
    {
      "name": "helloworld",
      "tags": ["centos", "debian", "ubuntu", "new"],
      "description": "description1",
      "file_name": "helloworld.sh",
      "updated_at": "2017-11-13 13:31:03",
      "type": "shell",
      "params": [
        {
          "name": "greeting",
          "description": "Greeting text",
          "required": false,
          "type": "input"
        },
        {
          "name": "mode",
          "type": "select",
          "select_values": ["fast", "slow"]
        }
      ]
    }
  ]
}
```
File details
Additional fields of the recipe :
- type — script interpreter type. Allowed values: shell , ansible , power_shell . If the field is not specified, the value shell ;
- params — array describing the parameters requested from the user when the script is launched. Each element of the array params may contain:
  - name — parameter name (required field);
  - description — parameter description;
  - required — whether the parameter is required when launching the script. By default false ;
  - type — parameter input field type. Allowed values: input or select . Default input ;
  - select_values — list of allowed values for the drop-down list. Required if type equals select .

On the platform server:

Obtain an authorization token:
```
curl -k -X POST -H "accept: application/json" -H "Content-Type: application/json" 'https://domain.com/auth/v4/public/token' -d '{"email": "admin_email", "password": "admin_pass"}'
```
Comments to the command

domain.com — domain name or IP address of the server with the platform
admin_email — platform administrator's email
admin_pass — platform administrator's password

In response, you will get the message in the form:
Example of response in JSON
```
{
  "confirmed": true,
  "expires_at": null,
  "id": "6",
  "token": "4-e9726dd9-61d9-2940-add3-914851d2cb8a"
}
```
Save the received token value.
Run an API request to create the repository in the platform:

curl -H 'x-xsrf-token: <token>' -X POST https://localhost/vm/v3/repository -d '{"name":"<repo_name>","url":"<repo_url"}'

Command details

Supported metadata.json parameters

The following is a list of parameters processed when synchronizing the script repository. Some of them are not described in the JSON schema but are supported by the platform.

Attention!

The JSON schema does not prohibit additional fields, so extra parameters are not rejected during validation;
fields type and params are supported by the platform but are not described in the JSON schema, so their presence and format are not checked during validation;
fields tags , type and params in the recipe are not marked as required in the JSON schema, but have specific processing behavior:
- tags — if the field is missing, the script will not be saved;
- type — if the field is not specified, the value shell ;
- params — if the field is not specified, the script runs without additional parameters.

Top level

Parameter	Type	Required	Default	Description
`type`	string	yes	—	Repository type
`recipe`	array of object	yes	—	List of repository scripts

Array element `recipe`

Field	Type	Required	Default	Description
`name`	string, up to 255 characters	yes	—	Script name
`description`	string, up to 255 characters	yes	—	Script description
`file_name`	string, up to 255 characters	yes	—	Script file name in the repository. Together with the repository address, it forms a download link
`updated_at`	string, date and time	yes	—	Date and time of the last script update. Used to track changes to the script file
`tags`	array of string	no	—	Script tags, for example `linux` , `windows` , `centos` , `ubuntu` . Determine which operating systems the script will be displayed for in the platform web interface
`type`	string	no	`shell`	Script execution method. Allowed values: `shell` , `ansible` , `power_shell`
`params`	array of object	no	—	Parameters requested by the platform from the user when launching the script

Array element `params`

Field	Type	Required	Default	Description
`name`	string	yes	—	Parameter name
`description`	string	no	—	Parameter description, displayed to the user when launching the script
`required`	bool	no	`false`	Whether the parameter is required when launching the script
`type`	string	no	`input`	Input field type. Allowed values: `input` — regular input field; `select` — drop-down list.
`select_values`	array	yes, if `type` = `select`	—	List of values for the drop-down list

Verifying the repository

Verification confirms that the repository is available for use in the platform.

To verify the repository:

In the platform web interface, in the Scripts section, check that scripts from the added repository are displayed.
Run a script from the repository on a VM.

If no scripts are displayed, check the list of repositories using an API request:

Connect to the server with the platform via SSH. For more information about connecting via SSH, see Workstation setup.
Obtain an authorization token:
```
curl -k -X POST -H "accept: application/json" -H "Content-Type: application/json" 'https://domain.com/auth/v4/public/token' -d '{"email": "admin_email", "password": "admin_pass"}'
```
Comments to the command

domain.com — domain name or IP address of the server with the platform
admin_email — platform administrator's email
admin_pass — platform administrator's password

In response, you will get the message in the form:
Example of response in JSON
```
{
  "confirmed": true,
  "expires_at": null,
  "id": "6",
  "token": "4-e9726dd9-61d9-2940-add3-914851d2cb8a"
}
```
Save the received token value.

Run the request:

`curl -H 'x-xsrf-token: <token>' -X GET 'https://domain.com/vm/v3/repository?where=%28type%20EQ%20%27recipe%27%29'`

Example response

{
  "last_notify": 17387,
  "list": [
    {
      "hidden": true,
      "id": 1,
      "immortal": true,
      "name": "recipe_repository",
      "os_count": 0,
      "storage": null,
      "type": "recipe",
      "url": "http://download.ispsystem.com/OSTemplate/vm6/recipes/"
    },
    {
      "hidden": false,
      "id": 22,
      "immortal": false,
      "name": "testrepo",
      "os_count": 0,
      "storage": null,
      "type": "recipe",
      "url": "http://<IP>/recipes/"
    },
    {
      "hidden": false,
      "id": 34,
      "immortal": false,
      "name": "myrepo",
      "os_count": 0,
      "storage": null,
      "type": "recipe",
      "url": "http://<IP>/"
    }
  ],
  "size": 3

Updating the script list

The script list in the platform is synchronized with the repository every 15 minutes. To update the script list manually:

Obtain an authorization token:
```
curl -k -X POST -H "accept: application/json" -H "Content-Type: application/json" 'https://domain.com/auth/v4/public/token' -d '{"email": "admin_email", "password": "admin_pass"}'
```
Comments to the command

domain.com — domain name or IP address of the server with the platform
admin_email — platform administrator's email
admin_pass — platform administrator's password

In response, you will get the message in the form:
Example of response in JSON
```
{
  "confirmed": true,
  "expires_at": null,
  "id": "6",
  "token": "4-e9726dd9-61d9-2940-add3-914851d2cb8a"
}
```
Save the received token value.
Run the API request:
```
curl -H 'x-xsrf-token: <token>' -X POST "https://domain.com/vm/v3/repository/<repo_id>/update" -d ''
```
Command details
- <token> — authorization token;
- domain.com — domain name or IP address of the platform server;
- <repo_id> — repository ID.

Useful tips