===================================================
Configuring your PyPI or Anaconda Repository mirror
===================================================

NOTE: This documentation is for versions of Anaconda Repository 2.26 and newer. For versions between 2.3.0 and 2.26,
see :ref:`2.23 documentation <mirrors-anaconda-repository-2.23>`.
For documentation of older versions, please see :ref:`2.2 documentation <mirrors-sync-configuration-2.2>`.


Before you begin
================

Anaconda Repository comes with the command line tool ``anaconda-mirror`` to mirror packages from Anaconda Cloud. An administrator
can customize which packages to mirror by creating a configuration file in ``$PREFIX/etc/anaconda-server/mirror/``, such as
`$PREFIX/etc/anaconda-server/mirror/my-mirror.yaml`` and specifying that configuration file in the arguments to ``anaconda-mirror``::

    anaconda-mirror --config-file my-mirror

- platforms (valid options are: 'linux-64', 'linux-32', 'osx-64', 'win-32', and 'win-64')
- package_list
- python_versions (valid options are: 2.6, 2.7, 3.3, 3.4, 3.5, 3.6)
- license_blacklist (valid options are:  AGPL, GPL2, GPL3, LGPL, BSD, MIT, Apache, PSF, Public-Domain, Proprietary and Other) * 
- blacklist
- whitelist
- accounts

Specifies the Anaconda Cloud accounts that will be mirrored. The default is the ``anaconda`` account.


Customizing the mirror
======================

There are additional configuration settings that can be used to customize the account that is
created on Anaconda Repository.

- account_mapping
- access (valid options are: authenticated, private, public)

The ``account_mapping`` setting defines what account name the mirror will be created with. The default is to
use the same account name as on Anaconda Cloud.

For example::

    account_mapping:
      anaconda: anaconda-mirror

The ``access`` setting defines what permissions mirrored packages will have on your Anaconda Repository mirror.

- api_domain
- api_token

These settings can be used if you wish to mirror from a different Anaconda Repository server, or if you wish to
mirror private packages from Anaconda Cloud.


Platform-specific mirroring
===========================

By default, the anaconda-mirror tool will mirror all platforms.  If you know that you will *not* need all platforms, it will save you time and disk space if you edit the YAML file to specify the platform(s) you want mirrored::

  platforms:
    - linux-64
    - win-32


Package-specific mirroring
==========================

In some cases you may want to mirror only a small subset of the Anaconda Repository.  Rather than blacklisting a long list of packages you do not want mirrored, you can instead simply enumerate the list of packages you DO want mirrored.

For example::

  package_list:
  - accelerate
  - pyqt
  - zope 

This example mirrors only the three packages: Accelerate, PyQt & Zope.  All other packages will be completely ignored.

Python version-specific mirroring
=================================

In some cases on a few versions

For example::

  python_versions:
  - 3.3

Mirrors only Anaconda packages built for Python 3.3.


"License blacklist" mirroring
=============================

As of Anaconda Repository 2.26.0, the Anaconda mirroring script supports license blacklisting for the following license families:

* AGPL 
* GPL2
* GPL3
* LGPL
* BSD
* MIT
* APACHE
* PSF
* PUBLICDOMAIN
* PROPRIETARY
* OTHER
* NONE

For example::

  license_blacklist:
    - GPL2
    - GPL3
    - BSD

Mirrors all the packages in the repository EXCEPT those that are GPL2-, GPL3-, or BSD-licensed, because those three licenses have been completely blacklisted.

NOTE: Older versions of Anaconda Mirror support only license blacklisting for GPL.  If you are using an older version of Anaconda Repository, see the documentation for :ref:`customizing your PyPI or Anaconda Repository mirror <mirrors-sync-configuration-2.2>`.


"Blacklist" mirroring
=====================

The blacklist allows access to all packages EXCEPT those explicitly listed.

For example::

  blacklist:
    - bzip2
    - tk
    - openssl

Mirrors the entire Anaconda Repository except the bzip2, tk, and openssl packages.


"Whitelist" mirroring
=====================

The whitelist functions in combination with either the license_blacklist or blacklist arguments, AND re-adds packages that were excluded by a previous argument.  

For example::

  license_blacklist:
    - GPL2
    - GPL3
  whitelist:
    - readline

Mirrors the entire Anaconda Repository EXCEPT any GPL2- or GPL3-licenses packages, but including readline, despite the fact that it is GPL3-licensed.  


Combining multiple mirror configurations
========================================

You may find that combining two or more of the arguments above is the simplest way to get the exact combination of packages that you want.

The *platform* argument is evaluated before any other argument.  For example::

    platforms:
      - linux-64
    package_list:
      - dnspython
      - shapely
      - gdal

Mirrors ONLY linux-64 distributions of the dnspython, shapely and gdal packages.

If the *license_blacklist* and *blacklist* arguments are combined, the *license_blacklist* is evaluated first, and the *blacklist* is a supplemental modifier::

    license_blacklist:
      - GPL2
    blacklist:
      - pyqt

In this example, the mirror configuration does not mirror GPL2-licensed packages. It does not mirror the GPL3 licensed package pyqt because it has been blacklisted. It does mirror all other packages in the repository.

If the *blacklist* and *whitelist* arguments are both employed, the *blacklist* is evaluated first, with the *whitelist* functioning as a modifier::

    blacklist:
     - accelerate
     - astropy
     - pygments
    whitelist:
     - accelerate

This mirrors all packages in the repository except astropy and pygments.  Despite being listed on the blacklist, accelerate IS mirrored because it is listed on the whitelist.
