39a-pin

README

39a-pin

Pin assets to the 39 Alpha Research (or other remote) IPFS node.

39 Alpha hosts all of its data, as well as it's website, on IPFS, and provides a publically accessible HTTPS gateway. All assets need to be pinned to the 39 Alpha IPFS node, once they've been added to IPFS, in order for the gateway to serve the content in a timely fashion as well as to ensure longevity of the data. In general, if no node in the IPFS network as a given asset pinned, it will eventually be lost. So, to make this process as simple as possible for our teams, we need a tool to handling this.

This is where 39a-pin comes in. What it does is fairly simple to describe: it takes accepts one or more IPFS CIDs at the command line, establishes an SSH connection to a server running IPFS, and pins each CID. If no CIDs are provided, then it reads a JSON-formatted data mapping from standard output, pinning each CID in the mapping (see ipfs-put and ipfs-fetch for more information on the data mapping format).

Getting Started

Provided you have Go installed, you can install 39a-pin by running

$ go install github.com/39alpha/ipfs-tools/39a-pin@latest

and you are all set!

Usage

The most basic use case is to provide an IPFS hash at the command line.

$ 39a-pin QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo
SSH Key Passphrase:
INFO: Pinned QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo

In the event that you have a running instance of ssh-agent(1), and your SSH key has been added to it, then you will not be prompted for your key's Passphrase:

% 39a-pin QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo
INFO: Pinned QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo

If you've have a JSON-formatted data mapping, say generated by ipfs-put and saved in a file called data.json, then you provide it's contents to 39a-pin in lieu of CIDs at the command line to pin all of the CIDs in the mapping. For example

$ cat data.json
{
  "QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc": "data/2021-03-05",
  "QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo": "data/mnist.gz"
}
$ cat data.json | 39a-pin
INFO: Pinned QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc
INFO: Pinned QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo
$ 39a-pin < data.json
INFO: Pinned QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc
INFO: Pinned QmUgcKN8xiEC5ce8RMHo9SEMdnMJPhNV6FSFMXtmw53eZo

That's pretty much it! Have fun

Additional Flags

$ ./39a-pin -h
Usage: ./39a-pin [OPTIONS] [CID...]

Pin assets to a remote IPFS node. If no CIDs are provided at the
command line, a JSON-formatted data mapping is read from standard
input and all CIDs in the mapping are pinned.

Options:
  -domain string
    	the server domain name or ip address (default "39alpharesearch.org")
  -i string
    	the private ssh key to use (default "/home/user/.ssh/id_rsa")
  -port int
    	the port to use (default 22)
  -user string
    	username on the server (default "user")

By default, 39a-pin assumes that your local username is the same as your username on the remote server. If that's not the case, you can use the -user option. It also assumes that you will be using a private RSA key stored in $HOME/.ssh/id_rsa, which you can change using -i. In principle, 39a-pin should be able to pin to non-39A nodes using the -domain and -port options.