Develop with the Edge CLI

CLI Authentication Update

The Edge CLI authentication method is being updated to enhance security and improve integration. This change will be handled entirely by the platform and will not require any action from users, either now or when the update takes effect.

If you have questions or would like more information, please contact the Edge Customer Success Team:
http://edge-support.enthought.com/

The Edge CLI is a command-line tool that allows you to interact with the Edge platform. You can use the Edge CLI to create, manage, and deploy applications on Edge.

With the Edge CLI you can do many of the actions described in Your First App in a simplified way.

Installing the Edge CLI

To install the Edge CLI, you need to have the Enthought Deployment Manager (EDM) and with that you can install the enthought_edge client and edge_cli:

$ edm shell
$ edm install enthought_edge edge_cli

In addition to the above packages, you need the same resource access as described in Your First App.

Then you can test the CLI with:

$ edge

Step 1: Initialize a new application

Before initializing an application, ensure Docker is installed and running on your machine. The Edge CLI relies on Docker to manage the application's containerized environment.

Prerequisite: Docker installation

You can install Docker by following the official instructions for your operating system:

• For macOS and Windows: Use Docker Desktop.
• For Linux: Use the appropriate package manager, or follow this guide.

Once Docker is installed, ensure it is running before proceeding with the Edge CLI commands.

In a terminal, execute the edge command to initialize a new application:

$ edge app init

This will log you into Edge (if necessary) and prompt you for the following:

? Application ID: my-app
? Create application in which organization? Default organization
? Application framework? Generic App
Do you want to create new application "my-app"? [Y/n]:

Answer Y to create the application. This will create a new directory with the name of the application ID in the current directory, download the example application for the chosen framework into that directory, create an EDM virtual environment, and create an application record in Edge.

Further edge app commands are performed from within the application directory:

$ cd my-app

Working with Applications from Any Directory

After initializing an application, the Edge CLI records its location in ~/.edge/cli_apps.yaml.
This registry enables most edge app commands to be run from any location, not just from within the application directory.

If you're running a command outside the application directory, the CLI will consult this registry to locate your application.

In that case, you can also optionally specify the application ID at the end of each command:

$ edge app build [OPTIONS] [APPLICATION_ID]

If you are already inside the application directory, the CLI detects the app automatically, and the registry or application ID is not needed.

The edge app init command is a special case: it should still be run from the directory where you want the application to be created.

Additionally, running edge app init inside an existing application directory without specifying a framework will update the app_config.yaml and re-register the application path in ~/.edge/cli_apps.yaml, if needed.

Step 2: Build and test

You can build the application with:

$ edge app build

This prompts you for the version to build as, with version 1.0.0 as the initial default:

$ ? Build to version: 1.0.0

If you override this default, it will build to the new version number and that becomes the new default working version.

Once built, you can do a basic "smoke test" with:

$ edge app check

This will launch the application, ensure it can be communicated with, then shut it down again.

If you want to interact with the application manually use:

$ edge app run

This launches your application where it can be found in your web browser at http://127.0.0.1:9000/. Once you are done, you can shut it down with Ctrl-C.

Step 3: Publish the application

Before publishing an application, ensure that:

1. You have a developer license for the Edge platform.
2. You have been assigned the developer role within your organization.

note

Without both a developer license and the appropriate role, you will not be able to publish applications. If you encounter permission errors during publishing, please contact your organization's administrator to verify your access level.

Once your application is built (as described in Step 2), you can publish it by running the following command:

$ edge app publish

You’ll be prompted to select the type of Edge application you’re publishing:

• Native App
• Hosted Native App
• Kubernetes App

After selecting the application type, the command will:

• Push your application to the Enthought Quay repository.
• Create an Application Version record in Edge.

Once published, your application will be available in the Edge Workbench and can be launched like any other native application.

Step 4: Additional CLI Commands

Versioning

$ edge app versions

Environment Access

$ edge app shell  # Enter app virtual environment
$ edge env build  # Rebuild EDM environment

Reset CLI Configs

$ edge reset cli_config   # Reset Login

$ edge reset known_apps   # Clear app Locations

Docker Credentials

$ edge docker login         # Log in to Quay
$ edge docker credentials   # View credentials

Edge Versioning

$ edge versions

Help & Debugging

$ edge app --help
$ edge -v <command>     # Verbose made for debugging

Managing Dependencies in app_deps

The app_deps.pip section in the application's app_config.yaml file manages Python package dependencies for the application.

Here is an example of the app_deps section (from the Generic template):

app_deps:
  edm:
  - flask
  - pip
  - setuptools
  - gunicorn
  - enthought_edge
  pip: []

The app_deps structure specifies the application's dependencies:

• edm: Dependencies installed via edm using a .zbundle file.
• pip: Dependencies installed via pip using the requirements.txt file.

Below is the relevant section of the Dockerfile:

# Create a default EDM environment using the application's bundle
RUN edm env import -f /tmp/app_environment.zbundle edm && edm cache purge --yes

# Add any 'pip' packages to the application environment
COPY requirements.txt /tmp/requirements.txt
RUN edm run -- python -m pip install -r /tmp/requirements.txt --no-cache-dir

This setup streamlines the process of managing and installing the required dependencies in the Docker workflow. Specifically:

1. Dependencies listed under app_deps.edm are managed via the .zbundle file.
2. Dependencies listed under app_deps.pip automatically generate a requirements.txt file in the application's directory. This file is then used to install Python packages within the Docker container.

How It Works

Defining Dependencies:

Add the required Python packages directly to the app_deps.pip section.

Generating requirements.txt:

The requirements.txt file will be automatically created based on the dependencies listed in app_deps.pip when you run edge app build.

This file will be located in the application's directory for easy inclusion in the Docker build process.

Installing Dependencies in Docker:

During the Docker build process, the requirements.txt file will be referenced.

The dependencies will be installed using the following command in the Dockerfile:

RUN pip install -r requirements.txt

User Responsibilities

Ensure that all necessary dependencies for your application are accurately listed in the app_deps.pip section.

If additional tools or package managers are preferred for managing dependencies, users are welcome to adopt them. However, official support is limited to the pip-based workflow described in this documentation. While EDM is also used internally, pip remains the only external package manager we officially support.

Limitations

This documentation and associated scripts are specifically designed to support dependency management using pip and requirements.txt. Alternative tools and workflows are not officially supported.

Users leveraging additional tools are responsible for independently configuring and maintaining their Dockerfile, as this is where the installation process occurs. Please note that this falls outside the scope of standard support.

Example

Here is an example of how to set up and use app_deps:

Add pip dependencies to app_deps:

app_deps:
   edm: [
    ...
   ]
   pip:
      - flask
      - requests
      - pandas

The generated requirements.txt:

flask
requests
pandas

By following this process, you can efficiently manage dependencies and ensure smooth integration into the Docker environment.

Handling Application Compatibility in Edge CLI

When working with the new Edge CLI alongside an older installed application, you might encounter compatibility issues during the build process. These issues arise because the configuration file format has changed, and the new CLI is designed for the updated format. Follow the steps below to resolve the issue:

Instructions

1. Trigger the Build

Run the following command to build your app:

$ edge app build

If your app's configuration is incompatible with the new CLI, the command will fail with a message indicating the need to upgrade.

2. Upgrade the App Configuration

Upgrade the application's configuration to the new format using:

$ edge app upgrade

This command updates the application's configuration file to match the requirements of the new Edge CLI. If the configuration is already compatible, the command will exit cleanly, confirming that no further changes are necessary.

3. Rebuild the App

Attempt the build again:

$ edge app build

This time, the build should succeed, as the configuration has been updated to ensure compatibility with the new CLI.

Troubleshooting

To troubleshoot issues with the Edge CLI, the following may be useful:

• Make sure the latest version of the Edge CLI is installed.
• If an edge command fails, use -v or --verbose for detailed logs to diagnose issues (e.g., edge -v app build), whether with configurations (e.g., Dockerfile, app_config.yaml) or other errors. This flag prints debugging messages, which may narrow down the issue.