@alwaysai/device-agent 0.0.13 → 0.0.15

package/readme.md

@@ -1,8 +1,9 @@
 # alwaysAI Device Agent
 
-The alwaysAI Device Agent is a tool that runs on an alwaysAI device provisioned
-for production remote deployment. It enables management of one or more alwaysAI
-apps on a particular device via a command line interface.
+The alwaysAI Device Agent enables provisioning devices and managing devices and
+applications in production deployments of alwaysAI Computer Vision applications.
+Once installed and running, it connects to the alwaysAI Cloud to enable remotely
+controlling the device and applications from the alwaysAI Dashboard.
 
 Note that the Device Agent is still in an experimental phase and these commands
 are likely to change. This guide will be updated with the latest usage as things
@@ -10,80 +11,125 @@ change.
 
 ## System Requirements
 
-* Recent version of Debian or Ubuntu
-* `npm` >= 7.0.0
-* `node` >= 16.0.0
-* Recent version of `docker` with user access
-  * On Linux: `$ sudo usermod -aG docker $USER`
-* Recent version of `docker-compose`
-* `curl` installed.
+* Supported OS:
+    * Debian Bullseye, Buster
+    * Ubuntu 20.04, 18.04
+    * NVIDIA Jetpack 4.6.x
+* Supported target architecture
+    * amd64
+    * aarch64
+    * armv7hf
+* `docker` version >= 19.03
+* `curl` installed (required to download provisioning scripts)
 
 ## Provision Device
 
-### Provision the device
-
-If you're system already meets all the system requirements, you can simply install the device agent via `npm`:
-
-```
-sudo npm install -g @alwaysai/device-agent@latest
-```
+### Install the alwaysAI Device Agent and dependencies
 
-Otherwise, you can run the provision script to install the agent and its dependencies:
+On the target device, run:
 
 ```
-curl -fsSL https://alwaysai-artifacts-prod.s3.us-west-1.amazonaws.com/device-agent/install-device-agent.sh | sudo -E bash -
+$ curl -fsSL https://artifacts.alwaysai.co/device-agent/install-device-agent.sh | sudo -E bash -
 ```
 
 The Device Agent will be available in the terminal as `aai-agent`.
 
-Next, log in to the Device Agent with the following command:
-
-```
-aai-agent login --email <username> --password <password> [--device <device_id>]
-```
+### Provision the device
 
-Note that if you already have a device registered with the alwaysAI cloud, you
-can optionally provide that device ID in the login command. If you don't yet
-have a device configured, follow the next step to initialize the device.
+Provisioning the device performs the following:
 
-### Initialize the alwaysAI device
+1. Create the device in the alwaysAI Cloud
+2. Obtain device credentials to connect to alwaysAI Cloud
+3. Run the alwaysAI Device Agent in the background
 
-After logging in, run the following command to initialize the current device as
-an alwaysAI device:
+Run the following command on the target device to provision it:
 
 ```
-$ aai-agent device init --name <name> [--description <description>]
+$ curl -fsSL https://artifacts.alwaysai.co/device-agent/provision.sh | bash -s -- --email <email> --password <password> [--device-name <device_name>]
 ```
 
-For example:
+Where:
+* `email` is the email associated with your alwaysAI account.
+* `password` is the password for your alwaysAI account.
+* `device_name` is an optional device name, which will be displayed on the
+  devices page of the alwaysAI Dashboard. If a device name is not provided, one
+  will be generated for you and logged to the console for reference.
+
+If you'd like to only provision the device, but not start the Device Agent in
+the background (skip step 3), run with the `--provision-only` flag:
 
 ```
-$ aai-agent device init --name test-dev-1 --description "Device for testing alwaysAI Device Agent"
+$ curl -fsSL https://artifacts.alwaysai.co/device-agent/provision-agent.sh | bash -s -- --email <email> --password <password> [--device-name <device_name>] --provision-only
 ```
 
-## Run an alwaysAI application on your device
+When the script completes, the device will be provisioned but the Device Agent will not be running in the background.
 
-### Publish an application release and install on device
+## Run an alwaysAI application on your device
 
 First, you must publish your application to the alwaysAI cloud. From the root
 of your application directory (where the `alwaysai.app.json` file is) on your
 development host:
 
 ```
-aai app configure
-aai app publish
+$ aai app configure
+$ aai app publish
 ```
 
 The output of the final command will give you the release hash that was
 published. You can run `aai release list --project <project_id>` to list all
 release versions for the project, where project ID can be found in the
-`alwaysai.project.json` file.
+`alwaysai.project.json` file. The application release will now show up on the
+project page of the alwaysAI Dashboard as well!
+
+Now you can deploy to your device from the alwaysAI Dashboard.
+
+## The alwaysAI Device Agent Command Line interface
+
+The Device Agent can also be used directly on the device with it's command line interface.
+
+```
+$ aai-agent --help
+Usage: aai-agent <subcommand> ...
+
+   Manage your alwaysAI production device
+
+Subcommands:
+
+   login              : Login to alwaysAI (this is meant for scripted environments)
+   app list           : List all installed apps
+   app install        : Install an alwaysAI app from a project
+   app status         : Get the status of an installed alwaysAI app
+   app start          : Start an installed alwaysAI app
+   app stop           : Stop a running alwaysAI app
+   app restart        : Restart running alwaysAI app
+   app logs           : Get logs for an application
+   app uninstall      : Remove an alwaysAI app
+   app show-models    : Show the application models
+   app add-model      : Add a model to an alwaysAI app
+   app remove-model   : Remove a model from an alwaysAI app
+   app replace-models : Replace all models of an alwaysAI app with new models
+   app update-models  : Update all models for an alwaysAI app
+   app get-all-envs   : Get environment variables for an application
+   app set-env        : Set environment variables for a service
+   device init        : Initialize device
+   device get-info    : Get device info
+   device clean       : Remove all provisioning files
+   get-model-package  : Download and unpack a model package
+```
+
+To see the output logs, run the following command:
+
+```
+export ALWAYSAI_LOG_TO_CONSOLE=1
+```
+
+### Install the application on the device
 
 Now you can install the application on the device using the device agent. Run
 the following on the device where the Device Agent is installed:
 
 ```
-aai-agent app install --project <project_id> [--release <release_hash>]
+$ aai-agent app install --project <project_id> --release <release_hash>
 ```
 
 ### Control the application
@@ -92,27 +138,27 @@ Run the following commands on the device where the Device Agent is installed:
 
 Get application status:
 ```
-aai-agent app status --project <project_id>
+$ aai-agent app status --project <project_id>
 ```
 
 Start the application:
 ```
-aai-agent app start --project <project_id>
+$ aai-agent app start --project <project_id>
 ```
 
 Show the application logs:
 ```
-aai-agent app logs --project <project_id>
+$ aai-agent app logs --project <project_id>
 ```
 
 Stop the application:
 ```
-aai-agent app stop --project <project_id>
+$ aai-agent app stop --project <project_id>
 ```
 
 Uninstall the application:
 ```
-aai-agent app uninstall --project <project_id>
+$ aai-agent app uninstall --project <project_id>
 ```
 
 ### Manage application models
@@ -126,9 +172,9 @@ application is already configured to be using that model ID, updating to the
 new model can simply be done with:
 
 ```
-aai-agent app stop --project <project_id>
-aai-agent app update-models --project <project_id>
-aai-agent app start --project <project_id>
+$ aai-agent app stop --project <project_id>
+$ aai-agent app update-models --project <project_id>
+$ aai-agent app start --project <project_id>
 ```
 
 #### Replace models for an application for new ID
@@ -137,9 +183,9 @@ If you'd like to install an entirely new model to an application, replacing the
 model the app was originally configured with, run the following command:
 
 ```
-aai-agent app stop --project <project_id>
-aai-agent app replace-models --project <project_id> --models <model_id_1> [<model_id_2> ...]
-aai-agent app start --project <project_id>
+$ aai-agent app stop --project <project_id>
+$ aai-agent app replace-models --project <project_id> --models <model_id_1> [<model_id_2> ...]
+$ aai-agent app start --project <project_id>
 ```
 
 If you plan on using this method, you can make your application source model ID
@@ -155,13 +201,13 @@ obj_detect = edgeiq.ObjectDetection(edgeiq._globals.MODEL_ID_LIST[0])
 To download a model package from the alwaysAI cloud and unpack to a specific directory, run:
 
 ```
-aai-agent get-model-package <model ID> [--path <destination path>]
+$ aai-agent get-model-package <model ID> [--path <destination path>]
 ```
 
 For example, to download `alwaysai/yolo_v3` to `~/alwaysai` run:
 
 ```
-aai-agent get-model-package alwaysai/yolo_v3 --path ~/alwaysai
+$ aai-agent get-model-package alwaysai/yolo_v3 --path ~/alwaysai
 ```
 
 Once the command completes, you'll see the model package in the
@@ -173,47 +219,12 @@ The Device Agent enables you to set and update environment variables for all
 services or a single service of you application.
 
 ```
-aai-agent app set-env <key=val> --project <project_id> [--service <service>]
+$ aai-agent app set-env <key=val> --project <project_id> [--service <service>]
 ```
 
 For example, to set the following environment variable for the `alwaysai`
 service run the following command on the device:
 
 ```
-aai-agent app set-env TEST_ENV=1 --project <project_id> --service alwaysai
+$ aai-agent app set-env TEST_ENV=1 --project <project_id> --service alwaysai
 ```
-
-## Device Agent Commands
-
-```
-$ aai-agent --help
-Starting alwaysAI Device Agent
-Usage: aai-agent <subcommand> ...
-
-   Manage your alwaysAI production device
-
-Subcommands:
-
-   login                   : Login to alwaysAI (this is meant for scripted environments)
-   app list                : List all installed apps
-   app list-releases       : List all releases for a given app
-   app list-latest-release : List the latest release hash for a given app
-   app install             : Install an alwaysAI app from a project
-   app status              : Get the status of an installed alwaysAI app
-   app start               : Start an installed alwaysAI app
-   app stop                : Stop a running alwaysAI app
-   app restart             : Restart running alwaysAI app
-   app logs                : Get logs for an application
-   app uninstall           : Remove an alwaysAI app
-   app rollback            : Rollback an alwaysAI app to the previous version
-   app show-models         : Show the application models
-   app add-model           : Add a model to an alwaysAI app
-   app remove-model        : Remove a model from an alwaysAI app
-   app replace-models      : Replace all models of an alwaysAI app with new models
-   app update-models       : Update all models for an alwaysAI app
-   app get-all-envs        : Get environment variables for an application
-   app set-env             : Set environment variables for a service
-   device init             : Initialize device
-   device get-info         : Get device info
-   get-model-package       : Download and unpack a model package
-```

package/src/application-control/backup.ts

@@ -1,4 +1,4 @@
-import * as rimraf from 'rimraf';
+import { rimraf } from 'rimraf';
 
 import { copyDir } from '../util/copy-dir';
 import { buildApp, getAppDir } from './utils';
@@ -11,7 +11,7 @@ export async function createAppBackup(props: { projectId: string }) {
   const { projectId } = props;
   const appDir = getAppDir(projectId);
   const backupAppDir = `${appDir}${BACKUP_EXT}`;
-  rimraf.sync(backupAppDir);
+  await rimraf(backupAppDir);
   await copyDir({ srcPath: appDir, destPath: backupAppDir });
   await AgentConfigFile().setAppBackup({ projectId });
   logger.info(`Backed up app ${projectId} to ${backupAppDir}`);
@@ -30,7 +30,7 @@ export async function rollbackApp(props: { projectId: string }) {
   });
   const appDir = getAppDir(projectId);
   const backupAppDir = `${appDir}${BACKUP_EXT}`;
-  rimraf.sync(appDir);
+  await rimraf(appDir);
   await copyDir({ srcPath: backupAppDir, destPath: appDir });
   await buildApp({ appDir });
   await AgentConfigFile().setAppInstalled({

package/src/application-control/index.ts

@@ -7,8 +7,6 @@ import {
 import { installApp, uninstallApp } from './install';
 import { rollbackApp } from './backup';
 import {
-  listAppReleases,
-  listAppLatestRelease,
   getAppStatus,
   startApp,
   getAppLogs,
@@ -26,8 +24,6 @@ export {
   installApp,
   uninstallApp,
   rollbackApp,
-  listAppReleases,
-  listAppLatestRelease,
   getAppStatus,
   startApp,
   getAppLogs,
@@ -40,7 +36,6 @@ export {
 
 // CLI-mode only
 import {
-  addModel,
   getAppModels,
   removeModel,
   replaceModels,
@@ -49,7 +44,6 @@ import {
 } from './models';
 
 export {
-  addModel,
   getAppModels,
   removeModel,
   replaceModels,

package/src/application-control/install.ts

@@ -1,6 +1,7 @@
-import * as rimraf from 'rimraf';
+import { rimraf } from 'rimraf';
 import * as fs from 'fs';
 import * as path from 'path';
+import { buildDockerImage } from 'alwaysai/lib/util/docker';
 import { JsSpawner, Spawner } from 'alwaysai/lib/util';
 import { getAppDir, downloadPackageUsingPresignedUrl, buildApp } from './utils';
 import { AppDetailsPacket } from '@alwaysai/device-agent-schemas';
@@ -11,21 +12,17 @@ import { ProjectJsonFile } from 'alwaysai/lib/core/project';
 import {
   getTargetHardwareType,
   AppJsonFile,
-  TargetJsonFile
+  TargetJsonFile,
+  appCleanDocker,
+  getPythonVenvPaths,
+  installPythonVenv,
+  installPythonReqs
 } from 'alwaysai/lib/core/app';
-import {
-  appCleanDockerComponent,
-  buildDocker
-} from 'alwaysai/lib/components/app';
-import {
-  appInstallComponent,
-  installVenv
-} from 'alwaysai/lib/components/app/app-install-component';
 import {
   DOCKERFILE,
-  DOCKER_IMAGE_ID_INITIAL_VALUE
+  DOCKER_IMAGE_ID_INITIAL_VALUE,
+  PYTHON_REQUIREMENTS_FILE_NAME
 } from 'alwaysai/lib/constants';
-import { appReleasePullComponent } from 'alwaysai/lib/components/release';
 import { runInDir } from '../util/run-in-dir';
 import { installModelsWithPresignedURLs } from './models';
 import { logger } from '../util/logger';
@@ -54,7 +51,7 @@ export async function getInstalledApps(): Promise<AppDetailsPacket[]> {
 export async function installApp(props: {
   projectId: string;
   appReleaseHash: string;
-  signedUrlsPayload?: SignedUrlPayloadType;
+  signedUrlsPayload: SignedUrlPayloadType;
 }): Promise<void> {
   const { projectId, appReleaseHash, signedUrlsPayload } = props;
   logger.info(`Installing ${projectId}:${appReleaseHash}`);
@@ -82,25 +79,11 @@ export async function installApp(props: {
 
   // download app package
   const localDest = path.join(appDir, `${path.basename(appReleaseHash)}.tgz`);
-  if (!signedUrlsPayload) {
-    await runInDir(
-      appReleasePullComponent,
-      [
-        {
-          yes: true,
-          project: projectId,
-          releaseHash: appReleaseHash
-        }
-      ],
-      appDir
-    );
-  } else {
-    const { appSignedUrl } = signedUrlsPayload.appInstallPayload;
-    await downloadPackageUsingPresignedUrl({
-      localDest,
-      presignedUrl: appSignedUrl
-    });
-  }
+  const { appSignedUrl } = signedUrlsPayload.appInstallPayload;
+  await downloadPackageUsingPresignedUrl({
+    localDest,
+    presignedUrl: appSignedUrl
+  });
 
   // Unpack app package and remove tar file
   await unPackApp({ spawner, localDest, appDir });
@@ -111,28 +94,11 @@ export async function installApp(props: {
   // NOTE: this process no longer checks project collaboration
   await checkValidProjectFiles({ appDir });
 
-  // install models, python venv, and docker image
-  if (!signedUrlsPayload) {
-    await runInDir(
-      appInstallComponent,
-      [
-        {
-          yes: true,
-          pull: true,
-          clean: true,
-          skipModels: false,
-          source: false
-        }
-      ],
-      appDir
-    );
-  } else {
-    await installAppBuildReqs({ appDir });
-    await installModelsWithPresignedURLs(
-      signedUrlsPayload.modelsInstallPayload,
-      path.join(appDir, 'models')
-    );
-  }
+  await installAppBuildReqs({ appDir });
+  await installModelsWithPresignedURLs(
+    signedUrlsPayload.modelsInstallPayload,
+    path.join(appDir, 'models')
+  );
 
   await buildApp({ appDir });
 
@@ -147,29 +113,43 @@ export async function installApp(props: {
 async function installAppBuildReqs(props: { appDir: string }) {
   const { appDir } = props;
   const targetJsonFile = TargetJsonFile(appDir);
-  const targetJson = targetJsonFile.readIfExists();
-  if (!targetJson) {
-    throw new Error('Target json file does not exist!');
+  const targetCfg = targetJsonFile.readIfExists();
+  if (!targetCfg || targetCfg.targetProtocol !== 'docker:') {
+    throw new Error('Target json file does not exist or is invalid!');
   }
 
   await runInDir(
     async () => {
-      const targetHostSpawner = targetJsonFile.readHostSpawner();
+      const hostSpawner = targetJsonFile.readHostSpawner();
 
-      await appCleanDockerComponent({ targetHostSpawner });
+      await appCleanDocker({ targetHostSpawner: hostSpawner });
 
-      await buildDocker({
-        targetJson,
-        targetJsonFile,
-        targetHostSpawner,
-        pull: true
+      const dockerImageId = await buildDockerImage({
+        targetHostSpawner: hostSpawner,
+        targetHardware: targetCfg.targetHardware,
+        dockerImageTag: targetCfg.dockerImageId,
+        pullBaseImage: true,
+        logger
       });
-
-      await installVenv({
-        targetJson,
-        sourceSpawner: targetHostSpawner,
-        targetJsonFile
+      targetCfg.dockerImageId = dockerImageId;
+      // FIXME: This should use async internally
+      targetJsonFile.update((cfg) => {
+        if (cfg.targetProtocol === 'docker:') {
+          cfg.dockerImageId = dockerImageId;
+        }
       });
+
+      const targetSpawner = targetJsonFile.readContainerSpawner();
+      const pythonVenvPaths = await getPythonVenvPaths({ targetCfg });
+      await installPythonVenv({ targetSpawner, pythonVenvPaths, logger });
+      if (await hostSpawner.exists(PYTHON_REQUIREMENTS_FILE_NAME)) {
+        await installPythonReqs({
+          reqFilePath: PYTHON_REQUIREMENTS_FILE_NAME,
+          targetSpawner,
+          pythonVenvPaths,
+          logger
+        });
+      }
     },
     [],
     appDir
@@ -218,13 +198,13 @@ export async function uninstallApp(props: {
   }
   try {
     await stopApp({ projectId });
-  } catch {
-    logger.warn(`Failed to stop ${projectId}, may be left running...`);
+  } catch (e) {
+    logger.warn(`Failed to stop ${projectId}, may be left running...\n${e}`);
   }
   await AgentConfigFile().setAppUninstalled({ projectId });
   // Delete application directory and backup
   const appDir = getAppDir(projectId);
-  rimraf.sync(appDir);
-  rimraf.sync(`${appDir}${BACKUP_EXT}`);
+  await rimraf(appDir);
+  await rimraf(`${appDir}${BACKUP_EXT}`);
   logger.info(`Completed uninstalling ${projectId}`);
 }

package/src/application-control/models.ts

@@ -20,11 +20,11 @@ import {
   buildApp,
   downloadPackageUsingPresignedUrl,
   getAppDir,
-  requireAppInstalled
+  requireAppReady
 } from './utils';
 import { MODEL_JSON_FILE_NAME } from 'alwaysai/lib/core/model';
 import { APP_MODELS_DIRECTORY_NAME } from 'alwaysai/lib/constants';
-import { readAppCfgFile, updateAppCfgFile, writeAppCfgFile } from './config';
+import { readAppCfgFile, writeAppCfgFile } from './config';
 import { AppConfig } from '@alwaysai/app-configuration-schemas';
 
 export async function getAppModels(props: { projectId: string }) {
@@ -49,26 +49,12 @@ export async function getAppModels(props: { projectId: string }) {
   return modelDetails;
 }
 
-export async function addModel(props: { projectId: string; modelId: string }) {
-  const { projectId, modelId } = props;
-  await requireAppInstalled({ projectId });
-
-  const appDir = getAppDir(projectId);
-  await appModelsAddComponent({
-    yes: false,
-    dir: appDir,
-    id: modelId,
-    addToProject: false
-  });
-  await buildApp({ appDir });
-}
-
 export async function removeModel(props: {
   projectId: string;
   modelId: string;
 }) {
   const { projectId, modelId } = props;
-  await requireAppInstalled({ projectId });
+  await requireAppReady({ projectId });
 
   const appDir = getAppDir(projectId);
 
@@ -90,7 +76,7 @@ export async function replaceModels(props: {
   modelIds: string[];
 }) {
   const { projectId, modelIds } = props;
-  await requireAppInstalled({ projectId });
+  await requireAppReady({ projectId });
 
   const appDir = getAppDir(projectId);
 
@@ -117,7 +103,7 @@ export async function replaceModels(props: {
 
 export async function updateModels(props: { projectId: string }) {
   const { projectId } = props;
-  await requireAppInstalled({ projectId });
+  await requireAppReady({ projectId });
 
   const appDir = getAppDir(projectId);
   await appModelsUpdateComponent({
@@ -223,6 +209,7 @@ export async function updateModelsWithPresignedUrls(props: {
     await restartApp({ projectId });
 
     logger.info(`Models installed for project ${projectId}`);
+    /* Leave error handling to higher level so errors are sent to cloud
   } catch (e) {
     logger.error(
       'Error updating app models from presigned URL, restoring models.',
@@ -231,6 +218,7 @@ export async function updateModelsWithPresignedUrls(props: {
     await spawner.rimraf(ogDir);
     await copyDir({ srcPath: restoreDir, destPath: ogDir });
     await writeAppCfgFile({ projectId, appCfg: ogAppCfg });
+    */
   } finally {
     await spawner.rimraf(tmpDir);
     await spawner.rimraf(restoreDir);

package/src/application-control/status.ts

@@ -1,9 +1,8 @@
 import compose from 'docker-compose';
-import { fetchAppReleaseHistory } from 'alwaysai/lib/infrastructure';
 import { JsSpawner } from 'alwaysai/lib/util';
 
 import { runDockerLogin } from '../docker/docker-cmd';
-import { getAppDir, requireAppInstalled } from './utils';
+import { getAppDir, requireAppInstalled, requireAppReady } from './utils';
 import {
   ServiceStatusPacket,
   AppStatePacket,
@@ -13,21 +12,6 @@ import {
 import { AgentConfigFile } from '../infrastructure/agent-config';
 import { logger } from '../util/logger';
 
-export async function listAppReleases(props: { projectId: string }) {
-  const { projectId } = props;
-  const releaseHistory = await fetchAppReleaseHistory(projectId);
-  return releaseHistory;
-}
-
-export async function listAppLatestRelease(props: { projectId: string }) {
-  const { projectId } = props;
-  const releaseHistory = await fetchAppReleaseHistory(projectId);
-  if (releaseHistory.length >= 1) {
-    return releaseHistory[0]['releaseHash'];
-  }
-  return undefined;
-}
-
 export async function getAppStatus(props: {
   projectId: string;
 }): Promise<AppStatePacket> {
@@ -117,7 +101,7 @@ export async function getAppLogs(props: {
   args?: string[];
 }): Promise<NodeJS.ReadableStream> {
   const { projectId, services, args } = props;
-  await requireAppInstalled({ projectId });
+  await requireAppReady({ projectId });
 
   const appDir = getAppDir(projectId);
 
@@ -143,7 +127,7 @@ export async function startApp(props: {
   dockerLoginToken?: string;
 }): Promise<void> {
   const { projectId, dockerLoginToken } = props;
-  await requireAppInstalled({ projectId });
+  await requireAppReady({ projectId });
 
   const appDir = getAppDir(projectId);
   if (dockerLoginToken !== undefined) {