Application bundles

Starting with EDM 1.10 (and Enthought Deployment Server 0.17), we have support for publishing full applications and delivering them to the desktop. This builds on the “bundle” functionality in EDM/EDS, which allows complete, unambiguous and immutable description of the Python environment within which applications run.

The basic workflow to create a bundle for an application is:

• Develop and test your app, making sure that all dependencies are available through EDM/EDS.
• Create a function somewhere in your code, and publish the function in a setuptools entry point. This function should return some configuration info in a dictionary: icons to create, name of the app, etc.
• Create an EDM bundle with your app & dependencies. Add a dependency on the special library “eam”, available in enthought/free, which EDM will use for the setup process.
• Upload the bundle to EDS using the hatcher tool.
• Congratulations! Your app is now installable via edm app install <name>.

Detailed workflow

Application bundles are normal EDM environment requirements bundles that contain the Enthought Application Manager (EAM) package.

How to Create

To create an application bundle one needs two steps:

1. Register a function callable with the enthought_app_metadata setuptools pkg_resources entry_point. The callable is expected to return a dictionary that follows the Metadata schema describing basic application metadata (e.g. version, user friendly name) and information on the commands to start the application and create desktop shortcuts.
2. Create an EDM bundle with the application requirements and the eam python package. The eam package provides a standard executable entry_point for deployment managers like EDM to execute configure, start and remove configuration tasks for each application.

Example setup.py:

from setuptools import setup

setup(
  name='eam_example_app',
  version='1.0.1',
  license='BSD',
  ...
  entry_points={
      'enthought_app_metadata': ['example_app = eam_example_app.info:info'],
  ...)

Example callable that returns application metadata:

import os
HERE = os.path.abspath(os.path.dirname(__file__))

def info():
  """ Provides information to the "eam" package.
  """
  icon = os.path.join(HERE, 'data', 'icon.ico')
  return {
      'name': 'EAM Example',
      'description': 'Some information here',
      'license': 'BSD',
      'copyright': '(c) 2018 Enthought',
      'version': u'1.0.1',
      'schema_version': 2,
      'commands': [
          {'name': 'hello',
           'command': 'example_app',
           'shortcut': 'desktop',
           'icon': icon,
           'schema_version': 2}]}

Note

• One needs to create a bundle with schema version 2.0 for applications.
• EDM 1.10.0 supports only one application per bundle so having more contributions to enthought_app_metadata in a python environment will be ignored.

example

Generate the edm bundle:

edm bundle generate -f mayavi_demo-1.0.2-1.bundle mayavi eam eam_mayavi_app pyside --version 2.7 -m 2.0 --arch=win-x86

Which creates an edm bundle for windows 32 bit for latest mayavi version in EDS using python 2.7.

Note

The eam_mayavi_app is a simple egg that registers the mayavi2 executable and icons with the eam package. This is necessary when the application is not eam aware. Custom applications do not have to use a separate egg to register with eam, but can register the necessary callable in their setup.py.

Upload

To upload the bundle we use the hatcher bundles command group.

example

$ hatcher bundles upload enthought free mayavi_demo-1.0.2-1.bundle

Which will upload our application bundle to the enthought/free repository.

Note

If the bundle is uploaded to any repository other than enthought/free, the edm yaml config file needs to be updated with a new bundle_repositories entry, pointing to the repository containing the bundle file. See documentation on EDM configuration for more.

Deployment

To deploy the application we use EDM and in particular the edm app/application command group to list, search, install, start and remove applications. To support these operations EDM relies on the fact that the eam package is part of the bundle requirements and installed in the created python environment.

example

List available applications

$ edm app list-available
Fetching indices for bundle repositories. done
name         version    repository
-----------  ---------  ------------------
mayavi_demo  1.0.0-3    enthought/free
mayavi_demo  1.0.0-4    enthought/free

This list will contain only bundles that use the eam python package.

Install application

$ edm app install mayavi_demo
Fetching indices for bundle repositories. done
Fetching indices for runtime repositories. done
Fetching indices for package repositories.. done
Installing runtime... done
VTK-7.0.0-2.egg                                         [fetch]
21.83 MiB [..................................................]   10.1 MiB/sec
Installing/removing package(s)
mayavi             [...........................................]

Note

EDM will download the bundle and create the python environment. Next EDM will ask the eam package to create the any shortcuts for the registered application.

Start application

$ edm app start mayavi_demo

In this case EDM with ask the eam package to start the registered application.