Metadata-Version: 1.1
Name: ipfscluster
Version: 0.1.2
Summary: HTTP Client for IPFS Cluster.
Home-page: https://gitlab.com/clearos/clearfoundation/py-ipfs-cluster-api
Author: ClearFoundation
Author-email: developer@clearfoundation.com
License: GPL-3.0
Description: |pipeline status| |coverage report|
        
        IPFS Cluster HTTP API
        =====================
        
        This is a python package to interact with the HTTP REST API of the IPFS
        cluster. `Full API
        documentation <https://clearos.gitlab.io/clearfoundation/py-ipfs-cluster-api>`__
        is available on gitlab pages.
        
        Installation
        ------------
        
        ``ipfscluster`` is available from the PyPI repository:
        
        .. code:: bash
        
           pip install ipfscluster
        
        Getting an IPFS Cluster Running
        -------------------------------
        
        To try the API out, you need to have a running IPFS cluster. The easiest
        way to get one of those is to use ``docker``. In the
        ``docker-compose.yml`` file shown below, you will need to adjust the
        ``volumes`` tags to reference actual folders on your host machine. The
        change in ``environment`` variables for ``ipfs_cluster`` service makes
        use the docker network DNS resolution by service name. Since our docker
        agent is called ``ipfs``, we can get its IP address in the internal,
        ``backend`` network by using ``ipfs`` as its DNS name.
        
        Copy this YML into a ``docker-compose.yml`` file in some folder and then
        run ``docker-compose up``.
        
        .. code:: yaml
        
           version: "3.7"
           services:
        
             ipfs:
               image: ipfs/go-ipfs:latest
               ports:
                 - "4001:4001"
                 - "5001:5001"
               networks:
                 - backend
               volumes:
                 - ~/ipfs/ipfs:/data/ipfs
        
             ipfs_cluster:
               image: ipfs/ipfs-cluster:latest
               ports:
                 - "9094:9094"
                 - "9095:9094"
                 - "9096:9096"
               volumes:
                 - ~/ipfs/ipfs-cluster:/data/ipfs-cluster
               networks:
                 - backend
               depends_on:
                 - ipfs
               environment:
                 - CLUSTER_IPFSHTTP_NODEMULTIADDRESS=/dns4/ipfs/tcp/5001
                 - CLUSTER_IPFSPROXY_NODEMULTIADDRESS=/dns4/ipfs/tcp/5001
        
             networks:
               backend:
        
        Try out the API
        ---------------
        
        Now that you have a cluster running, you can try the API out. Open a
        python CLI and try:
        
        .. code:: python
        
           client = connect()
           m = {'name': 'bytes',
                  'cid': {'/': 'QmZfF6C9j4VtoCsTp4KSrhYH47QMd3DNXVZBKaxJdhaPab'},
                  'size': 30}
           with client:
               r = client.add_bytes(b"Mary had a little lamb")
           assert r == m
        
        Running Unit Tests
        ------------------
        
        Running unit tests can prove to be a massive pain because the gitlab CI
        runner runs on docker. For a project like this that uses
        ``docker-compose``, we have to use ``docker-in-docker`` according to
        their instructions. However, the documentation is sparse and there are
        lots of dead-ends… Here are the steps to get the ``docker-compose.yml``
        file to work:
        
        1. Install a local ``gitlab-runner`` using
           ``brew install gitlab-runner``.
        2. ``gitlab-runner exec docker --docker-privileged test``. Notice that
           there is a ``--docker-privileged`` argument. Without that, the
           ``docker-in-docker`` won’t work.
        3. Make sure all the ``multiaddr`` reference the ``docker`` service
           (which hosts all the other containers using ``dind``).
        4. ``tox`` should work, but for some reason: running the tests using
           ``tox`` produces connection refused errors, whereas running straight
           with ``pytest`` does not. Something about the tox environment screws
           things up.
        
        .. |pipeline status| image:: https://gitlab.com/clearos/clearfoundation/py-ipfs-cluster-api/badges/master/pipeline.svg
           :target: https://gitlab.com/clearos/clearfoundation/py-ipfs-cluster-api/commits/master
        .. |coverage report| image:: https://gitlab.com/clearos/clearfoundation/py-ipfs-cluster-api/badges/master/coverage.svg
           :target: https://gitlab.com/clearos/clearfoundation/py-ipfs-cluster-api/commits/master
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Other Audience
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
