Zum Hauptinhalt springen

IPFS Cluster Configuration

This document provides information about the configuration of the IPFS Clusters.

Table of Contents​

Add Configuration Endpoint​

The configuration endpoint is used to add the configuration of the IPFS clusters. The body of the request should be in json format.

Cluster Configuration​

Each cluster may have the following configurations:

{
  "host": "ipfs-cluster", // IPFS cluster host. Required.
  "port": "443", // IPFS cluster port. Default is 9094.
  "user": "username", // IPFS cluster username for Basic Auth. Optional.
  "pass": "password", // IPFS cluster password for Basic Auth. Optional.
  "secure": true, // Use HTTPS. Default is true.
  // timeout duration is used for network operations. Default is 30s.
  // timeout must be passed as a Duration string in the format "1h30m".
  // Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
  "timeout": "30s",
  "addParams": {
    "local": false,
    "recursive": false,
    "hidden": false,
    "wrap": false,
    "shard": false,
    "streamChannels": false,
    // noPin indicates whether to pin the file to the IPFS cluster at the time of adding. Default is false.
    "noPin": true
  },
  "pinParams": {
    "replicationFactorMin": 0,
    "replicationFactorMax": 0,
    "name": "name",
    // expireIn is the duration after which the pin expires on the particular IPFS cluster.
    // expireIn must be passed as a Duration string in the format "1h30m".
    // Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
    // If omitted or invalid string, the pin will never expire.
    // Values lower than 60s (1m) will be ignored.
    "expireIn": "24h"
  }
}

The only required field is host. All other configurations might be skipped. Beware that the default port is 9094 and secure is true thus usage of HTTPS is default behavior.

Example request and Primary Cluster​

In the body of the request you can add multiple clusters on key clusters. The first cluster in the list is the primary cluster. The primary cluster is used to add files. The file is then pinned to all the clusters in the list including the primary cluster.

POST /v1/ipfs/config (adds IPFS cluster configuration)
Body​
{
  "clusters": [
    {
      "host": "ipfs-cluster",
      "port": "443",
      "user": "username",
      "pass": "password",
      "secure": true,
      "addParams": {
        "noPin": true
      },
      "pinParams": {
        "expireIn": "24h"
      }
    },
    {
      "host": "ipfs-cluster"
    }
  ]
}
Example cURL​
curl --location '{{seal_service_address}}/v1/ipfs/config' \
--header 'Content-Type: application/json' \
--data '{
    "clusters": [        
        {
            "host": "ipfs-cluster",
            "port": "443",
            "user": "username",
            "pass": "password",
            "secure": true,
            "addParams": {
                "noPin": true
            },
            "pinParams": {
                "expireIn": "24h"
            }
        },
        {
            "host": "ipfs-cluster"
        }
    ]
}'

Note: After adding the configuration, all instances of the seal service must be restarted to apply the changes and start using the new configuration.

Fallback configuration​

If IPFS cluster configuration is not yet added to the seal service, the service will use configuration from environment variables. The service requires IPFS cluster configuration and will fail to start if the configuration is not provided. Configuration from the environment variables is used only if configuration is not added to the service's Add Configuration Endpoint.

The following environment variables are used for IPFS cluster configuration:

IPFS_CLUSTER_HOST
IPFS_CLUSTER_PORT
IPFS_CLUSTER_USER
IPFS_CLUSTER_PASS
IPFS_CLUSTER_SECURE