{"id":22489723,"url":"https://github.com/JoinColony/pinion","last_synced_at":"2025-08-02T22:31:04.959Z","repository":{"id":40947135,"uuid":"160754335","full_name":"JoinColony/pinion","owner":"JoinColony","description":"📌Pin orbit-db stores and ipfs hashes","archived":false,"fork":false,"pushed_at":"2024-01-24T17:40:14.000Z","size":3363,"stargazers_count":29,"open_issues_count":34,"forks_count":4,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-05-02T00:21:49.237Z","etag":null,"topics":["ipfs","orbit-db","pinning"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JoinColony.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-12-07T01:30:42.000Z","updated_at":"2024-01-19T10:25:55.000Z","dependencies_parsed_at":"2023-02-01T11:00:41.352Z","dependency_job_id":null,"html_url":"https://github.com/JoinColony/pinion","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoinColony%2Fpinion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoinColony%2Fpinion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoinColony%2Fpinion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JoinColony%2Fpinion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JoinColony","download_url":"https://codeload.github.com/JoinColony/pinion/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228500432,"owners_count":17930066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ipfs","orbit-db","pinning"],"created_at":"2024-12-06T17:20:31.073Z","updated_at":"2024-12-06T17:22:57.059Z","avatar_url":"https://github.com/JoinColony.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"/docs/img/pinion_color.svg\" width=\"600\" \"Pinion Logo\" /\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://circleci.com/gh/JoinColony/pinion\"\u003e\n    \u003cimg src=\"https://circleci.com/gh/JoinColony/pinion.svg?style=shield\"\n    title=\"CircleCi\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://renovatebot.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/renovate-enabled-brightgreen.svg\"\n    title=\"Renovate enabled\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://discord.gg/HDkjCqF\"\u003e\n    \u003cimg src=\"https://img.shields.io/discord/562263648173555742?logo=discord\" alt=\"Chat on Discord\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://build.colony.io/\"\u003e\n    \u003cimg src=\"https://img.shields.io/discourse/https/build.colony.io/status.svg\" title=\"Contribute!\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n# Pinion\n\nPinion is a lightweight pinning service that supports both IPFS content and [orbit-db](https://github.com/orbitdb/orbit-db) stores. It relies solely on [ipfs-pubsub-peer-monitor](https://github.com/ipfs-shipyard/ipfs-pubsub-peer-monitor), [orbit-db](https://github.com/orbitdb/orbit-db), and [js-ipfs-http-client](https://github.com/ipfs/js-ipfs-http-client) to communicate with an IPFS node.\n\nPinion can:\n\n- **Pin IPFS content**\n- **Pin orbit-db store content**\n- **Keep listening to updates from any given orbit-db store**\n\n## Installation\n\nTo install pinion, run:\n\n```bash\nyarn add global @colony/pinion\n```\n\nor\n\n```bash\nnpm i -g @colony/pinion\n```\n\n## Usage (for the impatient)\n\nAnd then run pinion passing an IPFS node endpoint and a pinning room:\n\n```bash\nPINION_ROOM=YOUR_PINNING_ROOM pinion\n```\n\nIn this configuration we're assuming some sensible defaults. See below.\n\n## Custom configuration\n\nPinion can be configured by either passing in the configuration programatically to its constructor (with the only required value being the room, see defaults in the example):\n\n```js\nimport Pinion from 'Pinion';\n\nconst pinner = new Pinion('YOUR_PINNING_ROOM', {\n  ipfsRepo: './ipfs',\n  ipfsPrivateKey: 'CAA...',\n  maxOpenStores: 100,\n  orbitDBDir: './orbitdb',\n});\n```\n\nOr using environment variables when running it from the command line:\n\n```bash\nPINION_IPFS_CONFIG_FILE=./ipfsConfig.production.json PINION_ROOM=YOUR_PINNING_ROOM PINION_IPFS_REPO=./ipfs PINION_IPFS_PRIVATE_KEY=\"CAA...\" PINION_MAX_OPEN_STORES=100 PINION_ORBIT_DB_DIR=./orbitdb pinion\n```\n\n#### `PINION_ROOM`\n\n(required)\n\nThe IPFS pubsub room pinion is going to join and listen to new messages to.\n\n#### `PINION_MAX_OPEN_STORES`\n\n(optional)\n\nYou can also specify the limit of how many stores you wanna keep open simultaneously by passing in an environment variable `MAX_OPEN_STORES`. The stores will be automatically allocated using a LRU algorithm. The limit is by default set to 100 stores.\n\n#### `PINION_IPFS_CONFIG_FILE`\n\n(optional)\n\nDefine a config file to use (see ipfsConfig.production.example.json for an example).\n\n#### `PINION_IPFS_PRIVATE_KEY`\n\n(optional)\n\nThe private key that is used to initialize the IPFS repo. Will generate a random key when omitted.\n\n#### `PINION_IPFS_REPO`\n\n(optional)\n\nYou can specify the an IPFS repo path of your preference. The default is `./ipfs`.\n\n#### `PINION_ORBIT_DB_DIR`\n\n(optional)\n\nYou can specify the orbit-db path option so stores data are kept in the place of your preference. The default is `./orbitdb`\n\n### Debug\n\nPinion is still on its infancy and you might need debug info or a more detailed output to figure out if it misbehaves. To run it on verbose/debug mode, please also set an environment var like so `DEBUG='pinner:*'`.\n\n## API\n\n### Requests\n\n#### `REPLICATE`\n\nOpens a store, loads it and keep listening to it until it's being cleaned up by the LRU cache.\n\n##### Parameters\n\n1.  `address` - An orbit-db-store address.\n\n##### Payload example\n\n```js\n {\n   type: 'REPLICATE',\n   payload: { address: '/orbitdb/Qma=/my-store' },\n };\n```\n\n---\n\n#### `PIN_HASH`\n\nRequest the IPFS node to pin the content hash.\n\n##### Parameters\n\n1.  `ipfsHash` - An IPFS multihash. Emits a `pinnedHash` event passing the ipfs hash back.\n\n##### Payload example\n\n```js\n {\n   type: 'PIN_HASH',\n   payload: { ipfsHash: 'Qma=...' },\n };\n```\n\n---\n\n#### Responses\n\n##### `HAVE_HEADS`\n\nPublished when the pinner has opened a store and it's ready. It will contain the count of heads that the pinner has for this store.\n\n##### Payload example\n\n```js\n {\n   type: 'HAVE_HEADS',\n   to: '/orbitdb/Qma=/my-store',\n   payload: {\n     address: '/orbitdb/Qma=/my-store/\u003csignature\u003e',\n     count: 100,\n     timestamp: 10010203993\n  },\n }\n```\n\n\n##### `ANNOUNCE_PINNER`\n\nPublished when the pinner has started, or in response to an `ANNOUNCE_CLIENT` message.\n\n##### Payload example\n\n```js\n {\n   type: 'ANNOUNCE_PINNER',\n   payload: {\n     ipfsId: 'Qm...',\n  },\n }\n```\n\n---\n\n## Contributing\n\nWe welcome all contributions to Pinion. You can help by testing, suggesting new features, improving performance or documentation.\n\nPlease read our [Contributing Guidelines](https://github.com/JoinColony/pinion/blob/master/.github/CONTRIBUTING.md) for how to get started.\n\n### To run the tests\n\nStart an ipfs node on localhost on port 4001. You can use the commands provided in the package.json using either `yarn ipfsd-go` or `yarn ipfsd-js` (Docker has to be running on your system).\n\nThen, in another terminal window do:\n\n```\nyarn test\n```\n\n## License\n\nPinion is [MIT licensed](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJoinColony%2Fpinion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJoinColony%2Fpinion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJoinColony%2Fpinion/lists"}