:notoc:

.. _software-envs:

=====================
Software Environments
=====================

.. currentmodule:: coiled

.. toctree::
   :maxdepth: 1
   :hidden:

   software_environment_creation
   software_environment_management
   software_environment_local
   software_environment_cli


A crucial part of doing your work is making sure you have the software packages
you need. Coiled helps you manage software environments by building Docker images
from `pip <https://pip.pypa.io/en/stable/>`_ and `conda <https://docs.conda.io/en/latest/>`_
environment files for you. You can then use these environments locally, remotely in a Dask cluster,
and can share them with your friends and colleagues.


Supported software specifications
---------------------------------

Coiled supports publicly accessible conda packages, pip packages, and/or Docker images
for creating software environments. You can also compose these steps by, for example, conda installing
packages into a custom Docker image.


Design
------

Coiled uses packaging conventions you're already familiar with. You can point Coiled
at a list of conda or pip pacakges:

.. code-block::

    coiled.create_software_environment(
        name="my-software-env",
        conda=["dask", "xarray=0.15.1", "numba"],
    )

or to a local conda ``environment.yml`` or pip ``requirements.txt`` file:

.. code-block::

    coiled.create_software_environment(
        name="my-software-env",
        conda="environment.yml",
    )

to have custom Docker images built and stored for later use. Note that
you do not need to have Docker installed for Coiled to build Docker images for you!


Usage
-----

You can use Coiled software environments equally well locally (e.g. on your laptop) or
on remote Dask clusters (e.g. running on AWS). You can even collaborate with your friends
and colleagues by easily sharing software environments.
