Building Anaconda Navigator applications

This tutorial describes how to build an Anaconda Navigator app of the Rodeo IDE.

The conda build recipe for Rodeo is generated by conda skeleton. Three modifications to the files in the build recipe are required to declare the package as an app. The package is built and uploaded to your Anaconda Cloud channel. After adding the channel in Navigator, the app appears on the Home tab.

NOTE: Applications to be built for Navigator should have a graphical user interface (GUI). Not all conda packages have GUIs.

Who is this for?

This tutorial is for Windows, macOS and Linux users who wish to generate a Navigator app conda package from a PyPI package. Prior knowledge of conda build or conda recipes is recommended.

Before you start

Creating a skeleton recipe

  1. In your user home directory, run the conda skeleton command:

    conda skeleton pypi rodeo
    

    This creates a directory named rodeo and creates 3 skeleton files in that directory: meta.yaml, build.sh and bld.bat.

  2. Use the ls command on macOS or Linux or the dir command on Windows to verify that the skeleton files have been created.

Modifying requirements in meta.yaml

  1. Open the meta.yaml file in a text editor.
  2. In the requirements section, change the ipython entries to jupyter.

The full requirements section should look like this:

requirements:
  build:
    - python
    - setuptools
    - jupyter
    - flask >=0.10.1
    - docopt
    - pyzmq >=13
    - mistune

  run:
    - python
    - jupyter
    - flask >=0.10.1
    - docopt
    - pyzmq >=13
    - mistune

Entering the app in meta.yaml

To declare a conda package as an app, you must add the app parameter to the meta.yaml file. The app section contains four keys: entry, icon, summary and type.

The entry tag defines how Navigator is to launch the package. For the Rodeo IDE, separate entry tags are required for Windows, macOS and Linux.

  1. Open the meta.yaml file in a text editor.

  2. Add the following lines:

    • For Windows and Linux, add the entry tag:

      app:
        entry: rodeo .                              [win]
        entry: rodeo .                              [linux]
      
    • For macOS, you must provide a launch script:

      1. In a text editor, create a new file in the conda build recipe directory called rodeo_mac.command. Add the following code:

        DIR=$(dirname $0)
        
        $DIR/rodeo ${HOME}
        
      2. To make sure that the file gets installed, add these lines to the build.sh script:

        if [ `uname` == Darwin ]
        then
            cp $RECIPE_DIR/rodeo_mac.command $PREFIX/bin
        fi
        
      3. Add this line to the app section in meta.yaml:

        entry: open ${PREFIX}/bin/rodeo_mac.command [osx]
        
      4. A logo PNG file to be displayed in Navigator is provided in the conda build recipe. Download the app.png file from https://github.com/yhat/rodeo/blob/master/resources/app.png directly from the Github repository to the directory that contains the meta.yaml file.

The completed app section should look like this:

app:
  entry: rodeo .                              [win]
  entry: rodeo .                              [linux]
  entry: open ${PREFIX}/bin/rodeo_mac.command [osx]
  icon: app.png
  summary: Rodeo Data Science IDE
  type: web

You can download full versions of the meta.yaml and build.sh files.

Building

To make the package available on all platforms, you need to build and upload the rodeo package separately on Windows, macOS and Linux machines.

Use conda build to create the package:

conda-build rodeo

When conda build is finished, it displays the path and filename of the conda package.

If the conda-build command fails, see Troubleshooting a sample issue.

Windows example file path:

C:\Users\jsmith\Miniconda\conda-bld\win-64\rodeo-0.4.4-py35_0.tar.bz2

macOS example file path:

/Users/jsmith/miniconda/conda-bld/osx-64/rodeo-0.4.4-py35_0.tar.bz2

Linux example file path:

/home/jsmith/miniconda/conda-bld/linux-64/rodeo-0.4.4-py35_0.tar.bz2

NOTE: Your path and filename vary depending on your installation and operating system. Save the path and filename information for the next task.

Uploading to Cloud

  1. In a Terminal window or an Anaconda Prompt, navigate to your root conda environment.

  2. Log in to Cloud:

    anaconda login
    
  3. When prompted, enter your Cloud account name and password.

    If the login is successful, you see output similar to the following:

    Using Anaconda Cloud api site https://api.anaconda.org
    Username: defusco
    defusco's Password:
    login successful
    
  4. Now that you are logged into your channel, upload the Rodeo conda package:

    • On Windows:

      anaconda upload C:\Users\jsmith\Miniconda\conda-bld\win-64\rodeo-0.4.4-py35_0.tar.bz2
      
    • On macOS and Linux:

      anaconda upload /home/jsmith/miniconda/conda-bld/linux-64/rodeo-0.4.4-py35_0.tar.bz2
      

      NOTE: Change your path and filename to the exact path and filename you saved in Building. Your path and filename vary depending on your installation and operating system.

For more information about Cloud, see the Anaconda Cloud documentation.

Configuring Navigator

Now that you have uploaded the Rodeo package to your Cloud channel, you need to add the channel to Navigator.

  1. Launch Navigator:

    • On Windows and Linux, use the Start menu.
    • On macOS, you can launch it from the Desktop or through Spotlight.
  2. On the far left, open the Environments tab:

    ../../_images/conda_navigator-home.png

  3. Add your channel:

    1. Click the Channel button.

    2. Click the Add button.

    3. Type the URL to your Cloud channel:

      https://conda.anaconda.org/CHANNEL
      

      NOTE: Replace CHANNEL with your Cloud user name.

    4. Click the Update Channels button:

      ../../_images/conda_navigator-channel.png

      Navigator closes and then restarts. The Rodeo app is displayed on the Home tab:

      ../../_images/conda_navigator-rodeo.png

Troubleshooting

Conda build fails

If the conda recipe fails to build, see Troubleshooting.

App does not appear on the home pane

  • Check that the conda package has been uploaded to your Cloud channel.

  • Check that your channel has been added to the Channels list.

  • You may have to remove your .anaconda/navigator directory and then restart Navigator.

    NOTE: On Windows, macOS and Linux, .anaconda/navigator is in your Home directory.

App does not launch

Check that the app works correctly from the command line:

conda run rodeo

If rodeo starts correctly, you may have to remove your .anaconda/navigator directory and restart Navigator.

NOTE: On Windows, macOS and Linux, .anaconda/navigator is in your Home directory.

More information

See ../../commands/build/conda-skeleton-pypi for more options.

For more information about adding Start menu items in Windows, see the menuinst documentation.