Develop with the Edge CLI
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.
Running Commands: Inside vs. Outside the Application Directory
Most edge
commands can be run in one of two ways:
Inside the application directory: The CLI automatically detects the app based on the local
app_config.yaml
.Outside the application directory: The CLI uses the global registry (
~/.edge/cli_apps.yaml
) to locate the app. You can also explicitly provide theAPPLICATION_ID
in the command.
Example:
$ edge app build [OPTIONS] [APPLICATION_ID]
If you’re inside the application directory, the APPLICATION_ID
is not needed.
The edge app init
command should be run from the directory where you want the application created.
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
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:
- You have a developer license for the Edge platform.
- You have been assigned the developer role within your organization.
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:
- Hosted Native App
- 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 viaedm
using a.zbundle
file.pip
: Dependencies installed viapip
using therequirements.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:
- Dependencies listed under
app_deps.edm
are managed via the.zbundle
file. - Dependencies listed under
app_deps.pip
automatically generate arequirements.txt
file in the application's directory. This file is then used to install Python packages within the Docker container.
How It Works
Defining EDM Dependencies
Add required packages under the app_deps.edm
section. These dependencies are bundled into a .zbundle
file, which is imported during the Docker build to create the application's EDM environment.
Defining pip 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.
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.