=================
Using cas-mirror
=================


The cas-mirror tool is a component of the Anaconda Repository
Enterprise product.

The cas-mirror tool makes an exact copy of Anaconda's package
Repository, or part of it, on a your local Repository server.

For more information about the cas-mirror tool's functionality
and configurable options, see
:doc:`../../install/config/mirrors/index`.

Installing cas-mirror
=====================

To install the mirror tool, run::

    conda install cas-mirror

After cas-mirror has been installed, the following commands are
available::

    cas-sync --help
    cas-merge --help
    cas-sync-api-v4 --help
    cas-server --help


Using the cas-sync command
==========================

The ``cas-sync`` command brings the local mirror of Repository
up-to-date with our remote servers.

To configure the location of the mirror on your file system,
check the output of::

  cas-sync --config

If necessary, create a configuration file, either
``~/.cas-mirror`` or system-wise ``/etc/cas-mirror``, which contains
the desired location of the local mirror on the file system, the
platforms that should be mirrored and an optional blacklist of
packages that which should not be mirrored.

EXAMPLE::

  mirror_dir: /home/data/mirror
  remote_url: ""  # where to get miniconda and anaconda installers -- blank to skip
  # possible platforms are: linux-64, linux-32, osx-64, win-32, win-64 platforms:
    - linux-64
    - win-32
  blacklist:
    - dnspython
    - shapely
    - gdal



Once you are satisfied with the mirror directory---which may be the
default---run::

  cas-sync

Running this command for the first time takes many hours, because
the entire Repository is being downloaded. Subsequent runs take
significantly less time.


Using the cas-server command
=============================

You need to run ``cas-server`` as root when you intend to serve
on port 80.

To serve repository over HTTP, run::

  cas-server

If needed, use the ``--port`` option to change the port on which
the repository is being served.

Using the "delta" option
========================

If you've already downloaded most of the anaconda repository, and you're
only interested in the changes since ``cas-sync`` was last run, you can use
the ``delta`` configuration option::

   mirror_dir: /home/data/mirror
   remote_url: ""  # where to get miniconda and anaconda installers -- blank to skip
   # possible platforms are: linux-64, linux-32, osx-64, win-32, win-64
   platforms:
     - linux-64
     - win-32
   blacklist:
     - dnspython
     - shapely
     - gdal
   delta: true
   delta_dir: delta_pkgs

Instead of mirroring to the existing local repository, it will record
the necessary changes to bring the mirror up to date in a separate directory
(``delta_pkgs`` in this case). You can then use this generated directory to
update air-gapped mirrors using the ``cas-merge`` command.

The ``cas-merge`` command takes a delta directory and combines its contents
with an existing mirror directory. New packages are added, missing packages
are deleted, and the repodata is updated.

If instead of mirroring to a local directory, you want to make the changes
directly into an existing Anaconda Repository instance, the ``cas-sync-api-v4``
can be used. You'll need to use the ``dest_site`` config option::

   mirror_dir: /home/data/mirror
   remote_url: ""  # where to get miniconda and anaconda installers -- blank to skip
   # possible platforms are: linux-64, linux-32, osx-64, win-32, win-64
   platforms:
     - linux-64
     - win-32
   blacklist:
     - dnspython
     - shapely
     - gdal
   dest_site: some_site

Make sure that the site is defined in the anaconda config and you're properly
logged into it before invoking ``cas-sync-api-v4``.

More extensive information about the cas-mirror tool's functionality and
configurable options is available at :doc:`../../install/config/mirrors/customize-mirror`.
