Skip to main content

HTTP Client for IPFS Cluster.

Project description

pipeline status coverage report


This is a python package to interact with the HTTP REST API of the IPFS cluster. Full API documentation is available on gitlab pages.


ipfscluster is available from the PyPI repository:

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.

version: "3.7"

    image: ipfs/go-ipfs:latest
      - "4001:4001"
      - "5001:5001"
      - backend
      - ~/ipfs/ipfs:/data/ipfs

    image: ipfs/ipfs-cluster:latest
      - "9094:9094"
      - "9095:9094"
      - "9096:9096"
      - ~/ipfs/ipfs-cluster:/data/ipfs-cluster
      - backend
      - ipfs


Try out the API

Now that you have a cluster running, you can try the API out. Open a python CLI and try:

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ipfscluster-0.2.0.tar.gz (11.4 kB view hashes)

Uploaded Source

Built Distribution

ipfscluster-0.2.0-py2.py3-none-any.whl (23.7 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page