Edge Security Acceleration:Functions and Pages CLI tool

Introduction

You can use the ESA CLI to complete the following tasks.

• You can manage the full lifecycle of Functions and Pages locally, including creating Functions and Pages, publishing and deploying versions, and managing custom domain names or routing.

• You can debug functions in a local or private network environment. The CLI starts a local debugging service to simulate the production environment for functional testing.

• You can deploy projects with multiple files. The CLI automatically packages and builds project dependencies, such as npm files. This lets you deploy local Node.js projects to the cloud.

Common commands

The ESA CLI provides many commands to manage Functions and Pages. For more information about all commands, see https://github.com/aliyun/alibabacloud-esa-cli.

Prerequisites

Before installing the ESA CLI, you must install Node.js and npm. We recommend using a Node version manager, such as Volta or nvm, for the installation.

Use the ESA CLI

1. You can install the ESA CLI using npm. Then, you can view the CLI version and supported commands.

   npm install esa-cli -g    # Install the CLI globally
   esa-cli -v                    # View the CLI version
   esa-cli --help                # View the CLI commands

2. Log on to your account: You can obtain your AccessKey ID and AccessKey secret from the Alibaba Cloud Resource Access Management (RAM) console. Then, you can run the esa login command to log on to your account. If you only use the CLI to debug code locally, you do not need to log on.

   esa-cli login        # Log on
   esa-cli logout       # Log off

3. Initialize a project: To initialize a project, you can enter a project name, select a template, and follow the prompts from the initialization command to complete the process.

   esa-cli init

4. Debug locally: After you finish coding, you can debug the code locally using the CLI. When you run the esa-cli dev command, the entry file is automatically packaged and the local debugging service starts.

   

   Basic instructions:

   • You can press b in the interface to open the debug page in your browser.

   • You can press d to view the debug guide. Note: Chrome does not allow the command line to open the debug page. In the Chrome browser, open the Chrome://inspect#devices page. A running Remote Target appears. Click inspect below it to view console information. Note that EdgeRoutine code is server-side code. Because of this, the console on the preview page does not show output from the entry file's console. You must use inspect to debug.

   • You can press c to clear the panel.

   • You can press x to exit debugging.

   • You can use esa-cli dev --port <port> to temporarily specify a port.

   When you debug locally, you can also run the Edge Storage API and Cache API in your code.

   Note

   For the security of your online data, the edge storage service does not retrieve or set online data during local debugging. To simulate data locally, create a kv.json file in the root directory of the function project, at the same level as the esa.jsonc configuration file. Write data to the file in the following format:

   {
     "namespace": {
       "k1": "v1",
       "k2": "v2"
       }
   }

   The following code can then retrieve the simulated data:

   const edgeKv = new EdgeKV({ namespace: 'namespace' });
   async function run() {
    const data = await edgeKv.get('k1', { type: 'text' });
    console.log(data); // 'v1'
   }

1. Generate a version: After local debugging is complete, you can generate a code version for deployment.

   esa-cli commit      # Generate a version

2. Deploy online: After a version is generated, you can use deployment commands to deploy the version to public cloud points of presence (POPs).

   esa-cli deploy                          # Follow the prompts to select a version and target environment to deploy
   esa-cli deployments list                # View deployment status
   esa-cli deployments delete <versionId>  # Delete a specified version

3. Manage custom domains or routes:

   After deployment to the points of presence (POPs), you can configure custom domains or routes to access your Functions and Pages:

   1. Domain name: You can attach a domain name to your Functions and Pages. The domain name must be a subdomain of your ESA site. This lets you directly access the function through the domain name. In this case, Functions and Pages acts as the origin server for the domain name.

   2. Route: You can attach a route to your ESA site. Accessing the route triggers the execution of Functions and Pages. In this case, Functions and Pages can communicate with the site's origin server.

   # Domain name
   esa-cli domain list
   esa-cli domain add <domainName>     # Must be a domain name with ICP filling
   esa-cli domain delete <domainName>
   
   # Route
   esa-cli route list
   esa-cli route add [route] [site]
   esa-cli route delete <route>

4. Manage functions: You can view and delete functions using the CLI.

   esa-cli project list                  # View the function
   esa-cli project delete <PROJECT_NAME>   # Delete the function