Configuring environments and sample projects#

When you create a new project in Data Science & AI Workbench, you must select a base environment for the project. Anaconda provides several base Anaconda environments, along with Python, R, or Hadoop-Spark environments for you to choose from.

If these environments do not suit your needs, you can create a custom environment, then include it in the list of environments that are available upon project creation.

Creating your environment#

  1. Log in to Workbench as a user with administrator permissions.

    Tip

    The anaconda-enterprise user has the proper permissions.

  2. Click Create and select New Project.

  3. Select any Environment and Resource Profile, then click Create.

  4. Open a session for the project.

  5. Open a terminal in the project session.

  6. Configure conda to create new environments in the environments directory by running the following command:

    export CONDA_ENVS_DIRS=/opt/continuum/envs
export CONDA_PKGS_DIRS=/opt/continuum/envs/.pkgs

  7. Use conda to create or clone your custom environment.

    Here is an example command for creating a conda environment:

    # Replace <ENV> with a name for your new environment
conda create -y -n <ENV> python=3.8 ipykernel

    Here is an example command for cloning a conda environment:

    # Replace <CLONE_ENV> with the name of the environment you want to clone
# Replace <ENV> with a name for your new environment
conda create -y --clone <CLONE_ENV> --name <ENV>

    Caution

    python and ipykernel must be included in every environment you create for Workbench.

Providing your environment to users#

There are two methods for providing your environment to your users:

  • Place the environment in the sample projects gallery and allow other users to clone the environment as a project.

  • Include the environment as an available option in the Environment dropdown when creating a new project.

Both of these methods are accomplished by creating a project template archive (.tar.bz2) file that uses the environment you just created, and then placing the file in the correct directory.

The project template archive file must contain, at a minimum, the anaconda-project.yml file. For more information and help building projects, see the official Anaconda Project documentation.

  1. In your terminal, navigate to the project directory by running the following command:

    cd /opt/continuum/project

  2. Create a directory to store an anaconda-project.yml file for your custom environment by running the following command:

    # Replace <PROJECT> with the name of your project
mkdir <PROJECT>

  3. Create a copy of your current project’s anaconda-project.yml file in the directory you just created by running the following command:

    # Replace <PROJECT> with the name of your project
cp anaconda-project.yml <PROJECT>

  4. Enter the project directory you just created by running the following command:

    # Replace <PROJECT> with the name of your project
cd /opt/continuum/project/<PROJECT>

  5. Using your preferred file editor, edit the anaconda-project.yml file in your project directory to represent your custom environment. This involves updating the name:, description:, packages:, and env_specs: sections of the file.

    Tip

    Delete the commented section below env_specs: showing available packages. It is likely that these do not align with your custom environment.

    Note

    Your project’s name: will display on the Sample Projects grid or the Environments dropdown list after the project is created.

    Example anaconda-project.yml
    # Replace <PROJECT> with your projects name
# Replace <A_BRIEF_DESCRIPTION> with a description of your environment
# Replace <ENV> with the name of the environment you created or cloned

name: <PROJECT>

description: <A_BRIEF_DESCRIPTION>

packages:
    - python=3.8
    - ipykernel

platforms:
    - linux-64

env_specs:
    <ENV>: {}

  6. Create an archive file for the project, then set permissions for it by running the following commands:

    # Replace <PROJECT> with your project name
cd /opt/continuum/project
tar cfj <PROJECT>.tar.bz2 <PROJECT>
chmod 644 <PROJECT>.tar.bz2

    Note

    This archive file is the template that other projects will use as a starting point for their own projects.

  7. Move your project archive file to the sample project gallery by running the following command:

    # Replace <PROJECT> with your project name
mv /opt/continuum/project/<PROJECT>.tar.bz2 /gallery

  8. Enter the sample gallery directory by running the following command:

    cd /gallery

  9. (Optional) If you want to include the environment as an available option in the Environment dropdown when creating a new project, add the project archive file name (<PROJECT>.tar.bz2) to the TEMPLATES file. Save and close the file when complete. Otherwise, skip this step.

  10. Update the sample projects gallery to include your project by running the following command:

    python reindex.py

  11. Verify that you can either find and select your sample project on the Sample Projects page, or select your environment from the Environment dropdown when creating a new project.