Installation
Prerequisites
xcube releases are packaged as conda packages in the conda-forge channel. It is recommended to install xcube into a conda environment using the mamba package manager, which will also automatically install and manage xcube’s dependencies. You can find installation instructions for mamba itself here, if you don’t already have it installed.
In addition to mamba, there are alternative package managers available for conda environments:
The original
conda
tool. When considering this tool, please note that package installation and management with conda may be significantly slower than with mamba.The
micromamba
tool, a minimalistic, self-contained version of mamba.
Overview of installation methods
There are two main ways to install the xcube package:
Install an official release from a conda-forge package, using the mamba package manager. This method is recommended for most users.
Use mamba to install only xcube’s dependencies, but not xcube itself. Then clone the xcube git repository and install directly from your local repository. You should use this method if you intend to participate in the development of xcube, or if you need to use features that are so new that they are not yet available in an officially release conda-forge package.
These methods are described in more detail in the following sections.
Installation from the conda-forge package
To install the latest release of xcube into a new conda environment called
xcube
, run the following command.
mamba create --name xcube --channel conda-forge xcube
You can give the environment a different name by providing a different argument
to the --name
option.
To install xcube into an existing, currently activated conda environment, use the following command.
mamba install --channel conda-forge xcube
Installation from the source code repository
First, clone the repository and create a conda environment from it:
git clone https://github.com/dcs4cop/xcube.git
cd xcube
mamba env create
From this point on, all instructions assume that your current directory is the root of the xcube repository.
The mamba env create
command above creates an environment according to
the specifications in the environment.yml
file in the repository, which
by default takes the name xcube
. Then, to activate the environment and
install xcube from the repository:
mamba activate xcube
pip install --no-deps --editable .
The second command installs xcube in ‘editable mode’, meaning that it will
be run directly from the repository, and changes to the code in the repository
will take immediate effect without reinstallation. (As an alternative to
pip, the command python setup.py develop
can be used, but this is
no longer recommended.
Among other things, pip
has the advantage of allowing easy deinstallation of
installed packages.)
To update the install to the latest repository version and update the
environment to reflect to any changes in environment.yml
:
mamba activate xcube
git pull --force
mamba env update -n xcube --file environment.yml --prune
To install pytest
and run the unit test suite:
mamba install pytest
pytest
To analyse test coverage (after installing pytest as above):
pytest --cov=xcube
To produce an HTML coverage report:
pytest --cov-report html --cov=xcube
Docker
To start a demo using docker use the following commands
docker build -t [your name] .
docker run [your name]
docker run -d -p [host port]:8080 [your name]
Example 1:
docker build -t xcube:0.10.0 .
docker run xcube:0.10.0
This will create the docker container and list the functionality of the
xcube
cli.
Example 2:
docker build -t xcube:0.10.0 .
docker run -d -p 8001:8080 xcube:0.10.0 "xcube serve -v --address 0.0.0.0 --port 8080 -c /home/xcube/examples/serve/demo/config.yml"
docker ps
This will start a service in the background which can be accessed through port 8001, as the startup of a service is configured as default behaviour.
Installing soft dependencies
In addition to xcube’s ‘hard’ dependencies, which the standard installation methods install automatically when required, there are ‘soft’ dependencies. These are packages which are not required to install or use xcube, but enable additional functionality if they are present. Users who need this functionality should install the requisite soft dependencies explicitly. xcube’s current soft dependencies are listed below.
adlfs
: required by the abfs data store, which is used for access to Azure Blob storage. Trying to create an abfs data store withoutadlfs
installed will raise an exception advising that you install it.