{"id":23404816,"url":"https://github.com/zozs/whalesong","last_synced_at":"2025-04-11T21:22:26.656Z","repository":{"id":47614888,"uuid":"323928613","full_name":"zozs/whalesong","owner":"zozs","description":"Distributed container registry built on hypercores and IPFS","archived":false,"fork":false,"pushed_at":"2021-08-28T09:28:52.000Z","size":1923,"stargazers_count":25,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T17:21:19.249Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zozs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-23T14:50:48.000Z","updated_at":"2022-07-27T08:35:46.000Z","dependencies_parsed_at":"2022-09-21T02:01:54.624Z","dependency_job_id":null,"html_url":"https://github.com/zozs/whalesong","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zozs%2Fwhalesong","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zozs%2Fwhalesong/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zozs%2Fwhalesong/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zozs%2Fwhalesong/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zozs","download_url":"https://codeload.github.com/zozs/whalesong/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480715,"owners_count":21110999,"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":"2024-12-22T13:15:59.885Z","updated_at":"2025-04-11T21:22:26.625Z","avatar_url":"https://github.com/zozs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# whalesong\n\nDistributed container registry built on hypercores and IPFS\n\n## Installation\n\nRequirements:\n\n* Node 15 or later\n\nClone this repository, and install dependencies.\n\n```\ngit clone https://github.com/zozs/whalesong\ncd whalesong\nnpm install\n```\n\n## Usage\n\nLaunch the daemon by running\n\n`node index.js`\n\ninside the directory above. When the deamon is up, you now have a container registry listening on port 5005. You can then try to push and pull to the distributed registry.\n\n### Example\n\nAfter launching the daemon above, open a new shell, and try to pull and run the following test image, which will print a small greeting on your screen.\n\n```\n$ docker run localhost:5005/8361c37efa52cb2809f459fcf2559966dd384787f7ea6f0475c168ac069a31fb/hello:latest\nA distributed greeting to you, my friend :)\n```\n\nAlternatively, you can use the following commands to pull the same image, but using a human-readable name (see [Human-readable organisations/pubkeys](docs/human-readable-organisations.md) in `docs/` for an explanation on how this works).\n\n```\n$ docker run localhost:5005/whalesong.club/hello\nA distributed greeting to you, my friend :)\n```\n\nIf the example doesn't seem to work, or Docker returns `\"Not Found\"`, you may have to wait a minute or two if the sync is slow.\n\n### Pull an image\n\nA container image can be pulled using docker with\n\n`docker pull \u003curl of image\u003e`\n\nwhere the url will be of the following form for whalesong:\n\n`localhost:5005/8361c37efa52cb2809f459fcf2559966dd384787f7ea6f0475c168ac069a31fb/hello:latest`\n\nThe url consists of the following parts:\n\n* `localhost:5005`: The url of the registry that is running on your local machine. You will always use this url for both pulling from and pushing to the distributed registry.\n* `8361c37efa52cb2809f459fcf2559966dd384787f7ea6f0475c168ac069a31fb`: A long hexadecimal string, which is the encoded public key of the organisation/person whose image you want to pull or push. You can only push to public keys you own, but can pull from any public key you know of.\n* `hello:latest`: The image name (`hello`) and tag (`latest`) for the given image you want to pull. An organization or person may have multiple images and tags.\n\n### Push an image\n\nA container image can be pushed using docker with\n\n`docker push \u003curl of image\u003e`\n\nwhere the url must contain the url of the localhost registry,as well as your own public key, and the name you want to give your image. **Your own public key is printed when you launch the daemon.**\n\nFor example, assuming you have the public key `abcd1234`, and a Dockerfile in the current directory, build and push the image using:\n\n```\ndocker build -t localhost:5005/abcd1234/myownimage:latest .\ndocker push localhost:5005/abcd1234/myownimage:latest\n```\n\nAnyone else running `whalesong` can now pull your image using the url `localhost:5005/abcd1234/myownimage:latest` and run it on their own computer.\n\n### Other facts\n\nThe data is stored in the `~/.whalesong` directory in your home.\nIf you want to get a fresh start, you can delete it, but _your private keys will disappear_ so don't do this unless you know what you're doing.\n\n## Todo\n\n* Make container registry pass conformance tests (see [docs/conformance.md](docs/conformance.md)).\n* Support more registry operations, such as content discovery and content management.\n* Support multiple writable feeds from a single host.\n* Cleanup of unused blobs.\n* General reliability improvements.\n* Automatically prune old and failed/aborted uploads.\n* Extend tests.\n* Provide service files to launch whalesong on boot.\n* Build and push with kaniko in addition to current push/pull tests.\n* Multi-writer so that multiple hosts can write to a single feed.\n\n## License\n\nWhalesong is licensed under GNU AGPL v3 or later, see the `LICENSE` file for the full license.\n\n```\nwhalesong - distributed container registry\nCopyright (c) 2020, 2021, Linus Karlsson\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as\npublished by the Free Software Foundation, either version 3 of the\nLicense, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzozs%2Fwhalesong","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzozs%2Fwhalesong","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzozs%2Fwhalesong/lists"}