Usage

Interacting with an IPFS Node

The easiest way to interact with IPFS is via the Kaleido console and the simple IPFS user interface. From your environment panel:

  • Click the dropdown next to your IPFS node. Select View Dashboard.
    • This opens a new window. You have the option of leveraging existing application credentials to connect to the IPFS node or you can generate a new set of credentials specifically for your IPFS node.
    • If you choose to generate new credentials, copy them and store the secret somewhere safe.
    • You will always need to supply a set of active credentials corresponding to the IPFS node’s membership ID for any interactions with the IPFS node.
  • Click the OPEN IPFS WEB UI button at the bottom of the screen.
  • This will open a new window within which you can interact with your IPFS node and the rest of the network.

IPFS Web UI

Home screen

The Home screen within the IPFS UI will display specific details about the IPFS node. Namely it exposes: Peer ID, Protocol Version, Agent Version and Public Key.

Connections screen

The Connections screen displays all other IPFS nodes that are active in the environment. A peer to peer gossip protocol allows all IPFS nodes to immediately discover newly joined peers.

Files screen

Use the Files screen to create directory structures and upload files/images to the network. Create a new directory by clicking the Create Folder hyperlink and inputting a name for the folder. Add a new file to the network by clicking the Upload hyperlink and then selecting the desired file on your local system. If you want to upload the file into an existing directory, click into the folder and then use the Upload hyperlink.

Directed Acyclic Graph (DAG) screen

Use the DAG screen to view directory contents and to see the various shards of specific files. The DAG screen is particularly useful when you want to see a listing of all files in a directory and/or you want to download specific portions of a file. For example, perhaps you only want the first five minutes of an uploaded video.

IPFS API

If you prefer to programmatically interact with your IPFS node(s) there are two convenient endpoints for file upload and retrieval – /add & /cat

Upload

To upload a file use the /add endpoint and specify the path to file on your local machine. This call is a --form entry with name of the entry specified as “path” and the route to the local file supplied as a value. The IPFS endpoint must be fronted by a valid set of application credentials created against the same membership that provisioned the node.

For example, to upload a text file named file.txt from your $HOME directory:

curl --form "path=@/Users/johndoe/file.txt" https://u0kxkv4m7p:YFdCpp72cShpFqrhmy-EvBPUBzo9wgN1kVL5bs2e8Kg@zzol84uiv1-u0m93jbc8p-ipfs.kaleido.io/api/v0/add | jq

This will return a JSON object containing the file name, the hash and the file size.

For example:

{
  "Name": "file.txt",
  "Hash": "QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG",
  "Size": "21"
}

Download

Use the /cat endpoint along with a file hash to retrieve an uploaded file. By default files are returned as text representations of the referenced hash, therefore you are responsible for supplying a file name with the proper extension in order to successfully download properly formatted files. For example, to retrieve a .png file and output it into your $HOME directory:

curl https://u0kxkv4m7p:YFdCpp72cShpFqrhmy-EvBPUBzo9wgN1kVL5bs2e8Kg@zzol84uiv1-u0m93jbc8p-ipfs.kaleido.io/api/v0/cat/{file-hash} -o /Users/johndoe/image.png