Skip to content

Latest commit

 

History

History
176 lines (116 loc) · 5.41 KB

README.md

File metadata and controls

176 lines (116 loc) · 5.41 KB
Raw

grid_client

Version Lint Build Tests Nightly Code Coverage

Github repo: grid_client

grid_client is a client used for deploying workloads (VMs, ZDBs, k8s, etc.) on grid3.

Prerequisites

  • node 16.13.1 or higher
  • npm 8.2.0 or higher
  • may need to install libtool apt-get install libtool

Installation

Warning: For Qanet, Please use @2.5.2 version

Warning: For Testnet, Please use @2.5.2 version

Warning: For Mainnet, Please use @2.5.2 version

External package

yarn add @threefold/grid_client

Local usage

  • Clone the repository
git clone https://github.com/threefoldtech/tfgrid-sdk-ts.git
  • Install it
yarn install

Note: If the used Python version is 3.12 or later, you need to install setuptools.

python3 -m pip install setuptools

Getting started

Client configuration

  • Network environment: should select dev environment, qa, test or main.

  • Wallet connector: mnemonics (12 random words in a unique order) for your account to interact with the chain. Create one

  • Store secret: it's any word that will be used for encrypting/decrypting the keys on threefold key-value store.

  • Project name: it's a name to isolate the deployments into a namespace.

    Note: only network can't be isolated, all project can see the same network.

Create client instance

  • Here's a simple example of creating a client instance with the default configurations.

  • or you can check more advanced configuration here.

    async function getClient(): Promise<GridClient> {
  const gridClient = new GridClient({
    network: config.network,
    mnemonic: config.mnemonic,
  });
  await gridClient.connect();

  return gridClient;
}

  • You can set your configurations through environment variables or JSON config file as seen here.

  • With clientOptions being added, all urls are now configured. So, you can easily get the proxy URL for the used network simply by:

    const proxyURL = gridClient.clientOptions.proxyURL;

for more details, check client options

Important Note: grid client should be disconnected after finishing its usage.

gridClient.disconnect();

Using the client

This section assumes that you are using the client configuration from client_loader.ts

  • After creating a client instance you can call it in any of your scripts using getClient().

    const grid3 = getClient();

  • And then you can use this client instance with any of the client modules.

  • For example to deploy a VM you will need to use the machines module with the client and it can be used as follows. you can find the full example script here.

    • To deploy a VM

      await grid3.machines.deploy(vms);

    • To delete a VM

      await grid3.machines.delete({ name: vms.name });

  • More example scripts can be found here

Running the scripts

  • Before Running the scripts make sure you have a tsconfig.json file. here is an example file.

    {
  "compilerOptions": {
    "noImplicitAny": false,
    "module": "commonjs",
    "target": "esnext",
    "lib": ["ESNext", "DOM"],
    "types": ["node", "jest"],
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist/node",
    "esModuleInterop": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowJs": true,
    "baseUrl": "."
  },
  "include": ["src/**/*"]
}

  • After following the previous examples to create a client instance and using it in a script, you can then execute this script using ts-node.

    yarn run ts-node --project tsconfig-node.json filename.ts

Usage examples

API Docs

https://threefoldtech.github.io/tfgrid-sdk-ts/packages/grid_client/docs/api/index.html

Testing

Related Documentations