{"id":27185046,"url":"https://github.com/threefoldtech/qss-ipfs-pinningserver","last_synced_at":"2025-12-15T12:04:14.857Z","repository":{"id":61609125,"uuid":"536638366","full_name":"threefoldtech/qss-ipfs-pinningserver","owner":"threefoldtech","description":"ipfs pinning service","archived":false,"fork":false,"pushed_at":"2023-10-12T04:09:29.000Z","size":354,"stargazers_count":0,"open_issues_count":12,"forks_count":1,"subscribers_count":19,"default_branch":"development","last_synced_at":"2024-06-21T06:27:21.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/threefoldtech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-09-14T15:15:13.000Z","updated_at":"2024-06-21T06:27:21.064Z","dependencies_parsed_at":"2024-03-27T05:15:02.643Z","dependency_job_id":"9d04dbc8-7e13-4627-b18d-32109696bdab","html_url":"https://github.com/threefoldtech/qss-ipfs-pinningserver","commit_stats":null,"previous_names":["threefoldtech/tf-pinning-service"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fqss-ipfs-pinningserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fqss-ipfs-pinningserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fqss-ipfs-pinningserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/threefoldtech%2Fqss-ipfs-pinningserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/threefoldtech","download_url":"https://codeload.github.com/threefoldtech/qss-ipfs-pinningserver/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248074976,"owners_count":21043490,"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":[],"created_at":"2025-04-09T17:10:13.661Z","updated_at":"2025-12-15T12:04:09.494Z","avatar_url":"https://github.com/threefoldtech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 --\u003e\n\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\u003c!--\n*** Thanks for checking out the Best-README-Template. If you have a suggestion\n*** that would make this better, please fork the repo and create a pull request\n*** or simply open an issue with the tag \"enhancement\".\n*** Don't forget to give the project a star!\n*** Thanks again! Now go create something AMAZING! :D\n--\u003e\n\n\n\n\u003c!-- PROJECT SHIELDS --\u003e\n\u003c!--\n*** I'm using markdown \"reference style\" links for readability.\n*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).\n*** See the bottom of this document for the declaration of the reference variables\n*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.\n*** https://www.markdownguide.org/basic-syntax/#reference-style-links\n--\u003e\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n[![LinkedIn][linkedin-shield]][linkedin-url]\n\n\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/threefoldtech/tf-pinning-service\"\u003e\n    \u003cimg src=\"https://library.threefold.me/info/threefold/threefold__peoples_internet_.png\" alt=\"Logo\" width=\"100%\"\u003e\n  \u003c/a\u003e\n\n\u003ch1 align=\"center\"\u003eTF Pinning Service\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    IPFS Pinning Service over TF Quantum-Safe Storage\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/threefoldtech/tf-pinning-service\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"#\"\u003eView Demo\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/threefoldtech/tf-pinning-service/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/threefoldtech/tf-pinning-service/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails open\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#compile\"\u003eCompile\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#environment-variables\"\u003eEnvironment Variables\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#docker\"\u003eDocker\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#docker-compose\"\u003eDocker Compose\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n    \u003cli\u003e\u003ca href=\"#interacting-with-the-pinning-service\"\u003eInteracting With The Pinning Service\u003c/a\u003e\u003c/li\u003e\n    \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#using-the-http-api\"\u003eUsing the HTTP API\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#using-the-ipfs-cli\"\u003eUsing the IPFS CLI\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#using-the-ipfs-desktop-gui-app\"\u003eUsing the IPFS Desktop GUI app\u003c/a\u003e\u003c/li\u003e\n    \u003c/ul\u003e\n    \u003cli\u003e\u003ca href=\"#api-specs\"\u003eAPI Specs\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#compliance-test-suite\"\u003eCOMPLIANCE TEST SUITE\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\n\nIPFS pinning service backed by ThreeFold decentralized grid and Quantum Safe Filesystem.\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n### Built With\n\n* [Go](https://go.dev/)\n* [IPFS](https://ipfs.io/)\n* [QSFS](https://github.com/threefoldtech/0-stor_v2)\n* [Vue](https://vuejs.org/)\n\n\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nThreefold pinning service is a IPFS pinning service that complies with the IPFS Pinning Service API specification. it combines the content addressing capabilities of IPFS, the decentralized, Peer To Peer Internet infrastructure of Threefold, and Threefold's distributed and ultra-secure storage backend QSFS(Quantum-Safe Storage Filesystem) in order to achieve a powerful decentralized storage solution, wrapping the power of these systems into an easy-to-use service with simple rest API.\n\n### Prerequisites\n\n- An IPFS cluster with at least one IPFS peer.\n  - For development you can spin up a local IPFS Cluster instance. [setup instructions](https://docs.ipfs.tech/install/server-infrastructure/#create-a-local-cluster).\n  - For setup IPFS and IPFS Cluster on a production environment see [here](https://ipfscluster.io/documentation/deployment/)\n- The tfpin web service binary.\n  - You can download it from releases or compile from the source code.\n  If you need to compile from the source code, you will need also:\n    - An installation of Go 1.16 or later. [installation instructions](https://go.dev/doc/install)\n    - Git client\n\n\n### Compile\n\nTo compile tfpin binary from the source code, follow below instructions \n\n1 - Clone the repository:\n  - Open Terminal, Change the current working directory to the location where you want the cloned directory, and type\n  ```sh\n  git clone https://github.com/threefoldtech/tf-pinning-service.git\n  ```\n2- Compile:\n  - Change to `./tf-pinning-service` and type\n  ```sh\n  make build\n  ```\n\n  Then find the compiled binary file in `./bin` for current os and `./bin/linux_amd64` for linux os.\n\nOther make scripts available.\n\n```sh\nmake run        # run the web server\n```\n\n```sh\nmake build_run  # compile and run the web server\n```\n\nMake sure to set correctly the required environment variables. see below usage section.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\n1- set the required environment variables (see next section), then run the compiled binary\n\n```sh\nTFPIN_CLUSTER_HOSTNAME=\"cluster-host-name\" TFPIN_CLUSTER_USERNAME=\"usname\" TFPIN_CLUSTER_PASSWORD=\"password\" ./tfpin\n```\n\n2- You will need API token to interact with the service, for development run the script below to add a token of your choice (the development of the real sign-up flow blocked on the the chain part for now):\n\n```sh\ngo run ./scripts/add_test_tokens.go BestTokenEver\nToken `BestTokenEver` stored successfully.\n```\n\n### Environment Variables\n\n| Environment Variable  \t| Description  \t| Default Value  \t|\n|---\t|---\t|---\t|\n| TFPIN_CLUSTER_HOSTNAME  \t|   \t| 127.0.0.1  \t|\n| TFPIN_CLUSTER_PORT  \t|   \t| 9097  \t|\n| TFPIN_CLUSTER_USERNAME  \t|   \t| \"\"  \t|\n| TFPIN_CLUSTER_PASSWORD  \t|   \t| \"\"  \t|\n| TFPIN_CLUSTER_REPLICA_MIN  \t|   \t| -1 (Pin on all cluster IPFS peers) \t|\n| TFPIN_CLUSTER_REPLICA_MAX  \t|   \t| -1 (Pin on all cluster IPFS peers) \t|\n| TFPIN_DB_DSN  \t|   \t| pins.db  \t|\n| TFPIN_DB_LOG_LEVEL  \t|   \t| 1 (silent) \t|\n| TFPIN_SERVER_ADDR  \t|   \t| :8000  \t|\n| TFPIN_SERVER_LOG_LEVEL  \t|   \t| 3 (warn) \t|\n| TFPIN_AUTH_HEADER_KEY  \t|   \t| Authorization  \t|\n\n### Docker\n#### Building Image\n\nbuilding binaries with version information and other metadata will improve the monitoring, logging, and debugging processes by adding identifying information to help track the builds over time.\nthis why you should provide a value for the build arg `VERSION`.\n```sh\nVERSION=$([ ! -z \"$(git tag --points-at HEAD)\" ] \u0026\u0026 git tag --points-at HEAD || git rev-parse --short HEAD) # use current tag, if none, use commit hash\ndocker build --build-arg VERSION=\"$VERSION\" -t abouelsaad/tfpinsvc .\n```\n\n#### Running the container\n\n```sh\ndocker run -d --name tf-pin-svc --env TFPIN_CLUSTER_HOSTNAME=\"HOSTNAME\" --env TFPIN_CLUSTER_PORT=\"9094\" --env TFPIN_CLUSTER_USERNAME=\"USERNAME\" --env TFPIN_CLUSTER_PASSWORD=\"PASSWORD\" --env TFPIN_SERVER_ADDR=\":80\" -p 8000:80 abouelsaad/tfpinsvc\n```\n\nAdding test token\n\n```sh\ndocker exec tf-pin-svc ./add_test_tokens BestTokenEver\n```\n### Docker Compose\n\nFor development and testing, with one command you can spin up\n- an IPFS cluster, and\n- Threefold pinning service\n\nwhich is already configured to communicate, so you just need to get/add a test token, and start interacting with the service.\n\n```sh\ndocker compose up -d\ndocker exec tf-pin-svc ./add_test_tokens BestTokenEver\n```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- Interacting With The Pinning Service --\u003e\n## Interacting With The Pinning Service\n\nTo interact with the pinning service you can use any of:\n- IPFS Desktop or IPFS Web UI [installation instructions](https://github.com/ipfs/ipfs-desktop#install)\n- IPFS CLI [installation instructions](https://docs.ipfs.tech/install/command-line/)\n- Any http client, like `curl`\n\nSee Use pinning service [instructions](https://docs.ipfs.tech/how-to/work-with-pinning-services/#use-an-existing-pinning-service)\n\nThe threefold pinning service endpoint for all requests is\nhttps://[hostname]/api/v1/pins\n\n### Using the HTTP API\n#### Add a pin\n\n```sh\ncurl -X POST 'https://[HOSTNAME]/api/v1/pins' \\\n  --header 'Accept: */*' \\\n  --header 'Authorization: Bearer \u003cYOUR_AUTH_TOKEN\u003e' \\\n  --header 'Content-Type: application/json' \\\n  -d '{\n  \"cid\": \"\u003cCID_TO_BE_PINNED\u003e\",\n  \"name\": \"PreciousData.pdf\"\n}'\n\n```\n\n#### List successful pins\n\n```sh\ncurl -X GET 'https://[HOSTNAME]/api/v1/pins' \\\n  --header 'Accept: */*' \\\n  --header 'Authorization: Bearer \u003cYOUR_AUTH_TOKEN\u003e'\n```\n\n#### Delete a pin\n\n```sh\ncurl -X DELETE 'https://[HOSTNAME]/api/v1/pins/\u003cREQUEST_ID\u003e' \\\n  --header 'Accept: */*' \\\n  --header 'Authorization: Bearer \u003cYOUR_AUTH_TOKEN\u003e'\n```\n\n### Using the IPFS CLI\nThe IPFS CLI can be used to maintain pins by first adding the threefold pinning service.\n\n```sh\nipfs pin remote service add tfpinsvc https://[HOSTNAME]/api/v1/ \u003cYOUR_AUTH_TOKEN\u003e\n```\n\n#### Add a pin\n\n```sh\nipfs pin remote add --service=tfpinsvc --name=\u003cPIN_NAME\u003e \u003cCID\u003e\n```\n#### List successful pins\n\n```sh\nipfs pin remote ls --service=tfpinsvc\n```\n#### Delete a pin\n\n```sh\nipfs pin remote rm --service=tfpinsvc --cid=\u003cCID\u003e\n```\n\n### Using the IPFS Desktop GUI app\n\nsee [here](https://docs.ipfs.tech/how-to/work-with-pinning-services/#ipfs-desktop-or-ipfs-web-ui)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- API SPECS --\u003e\n## API Specs\n\nThreefold pinning service is compatible with the IPFS Pinning Service API (1.0.0) OpenAPI spec. \nsee [here](./pinning-api/README.md)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- COMPLIANCE TEST SUITE  --\u003e\n## COMPLIANCE TEST SUITE\nThis tool should be used as compliance test suite for IPFS Pinning Service API Spec.\nhttps://github.com/ipfs-shipyard/pinning-service-compliance\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- ROADMAP --\u003e\n## Roadmap\n\n- [ ] simple ipfs pining service server compatible with this OpenAPI spec (https://github.com/ipfs/pinning-services-api-spec).  \n- [ ] registration using smart contract\n- [ ] payment\n- [ ] Use QSFS as blocks storage layer\n\nSee the [open issues](https://github.com/threefoldtech/tf-pinning-service/issues) for a full list of proposed features (and known issues).\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the Apache License. See [`LICENSE`](LICENSE) for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nThreefold - [@threefold_io](https://twitter.com/threefold_io)\n\nProject Link: [https://github.com/threefoldtech/tf-pinning-service](https://github.com/threefoldtech/tf-pinning-service)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- ACKNOWLEDGMENTS --\u003e\n## Acknowledgments\n\n* [Pinning services api spec](https://ipfs.github.io/pinning-services-api-spec/)\n* [Work with pinning services](https://docs.ipfs.tech/how-to/work-with-pinning-services/#use-an-existing-pinning-service)\n* [Threefold quantum safe filesystem](https://library.threefold.me/info/manual/#/technology/threefold__qsfs)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#readme-top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/threefoldtech/tf-pinning-service.svg?style=for-the-badge\n[contributors-url]: https://github.com/threefoldtech/tf-pinning-service/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/threefoldtech/tf-pinning-service.svg?style=for-the-badge\n[forks-url]: https://github.com/threefoldtech/tf-pinning-service/network/members\n[stars-shield]: https://img.shields.io/github/stars/threefoldtech/tf-pinning-service.svg?style=for-the-badge\n[stars-url]: https://github.com/threefoldtech/tf-pinning-service/stargazers\n[issues-shield]: https://img.shields.io/github/issues/threefoldtech/tf-pinning-service.svg?style=for-the-badge\n[issues-url]: https://github.com/threefoldtech/tf-pinning-service/issues\n[license-shield]: https://img.shields.io/github/license/threefoldtech/tf-pinning-service.svg?style=for-the-badge\n[license-url]: https://github.com/threefoldtech/tf-pinning-service/blob/master/LICENSE.txt\n[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge\u0026logo=linkedin\u0026colorB=555\n[linkedin-url]: https://linkedin.com/in/linkedin_username\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Fqss-ipfs-pinningserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthreefoldtech%2Fqss-ipfs-pinningserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthreefoldtech%2Fqss-ipfs-pinningserver/lists"}