{"id":18607379,"url":"https://github.com/addono/container-registry-proxy","last_synced_at":"2025-04-10T20:32:13.929Z","repository":{"id":37028762,"uuid":"260135631","full_name":"Addono/container-registry-proxy","owner":"Addono","description":"A proxy for modifying requests to container registries using plugins.","archived":false,"fork":false,"pushed_at":"2024-03-27T19:42:52.000Z","size":2564,"stargazers_count":10,"open_issues_count":61,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-14T05:47:22.604Z","etag":null,"topics":["container-registry-proxy","devspace","docker","node","proxy","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/Addono/container-registry-proxy","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/Addono.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2020-04-30T06:52:43.000Z","updated_at":"2024-04-17T17:31:23.444Z","dependencies_parsed_at":"2023-02-19T07:15:56.942Z","dependency_job_id":"c5970d92-cce1-4997-bd88-be6f9934d418","html_url":"https://github.com/Addono/container-registry-proxy","commit_stats":{"total_commits":422,"total_committers":6,"mean_commits":70.33333333333333,"dds":0.6161137440758293,"last_synced_commit":"72b59ff1aeeececa849653b8a17471a304204f41"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Addono%2Fcontainer-registry-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Addono%2Fcontainer-registry-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Addono%2Fcontainer-registry-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Addono%2Fcontainer-registry-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Addono","download_url":"https://codeload.github.com/Addono/container-registry-proxy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248290041,"owners_count":21078923,"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":["container-registry-proxy","devspace","docker","node","proxy","typescript"],"created_at":"2024-11-07T02:29:16.150Z","updated_at":"2025-04-10T20:32:13.543Z","avatar_url":"https://github.com/Addono.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Container Registry Proxy\n\n[![License](https://img.shields.io/github/license/Addono/container-registry-proxy?style=flat-square)][gh-license]\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://img.shields.io/badge/project%20status-Active-greengrass?style=flat-square)](https://www.repostatus.org/#active)\n[![Depfu](https://img.shields.io/depfu/Addono/container-registry-proxy?style=flat-square)][crp-depfu]\n[![Docker Pulls](https://img.shields.io/docker/pulls/addono/container-registry-proxy?style=flat-square)][crp-hub]\n[![npm](https://img.shields.io/npm/dt/container-registry-proxy?style=flat-square)][crp-npm]\n[![npm](https://img.shields.io/npm/v/container-registry-proxy?style=flat-square)][crp-npm]\n[![GitHub stars](https://img.shields.io/github/stars/Addono/container-registry-proxy?style=flat-square)][gh-stars]\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)\n\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\n## 📝 Table of Contents\n\n- [About](#about)\n- [Getting Started](#getting_started)\n- [Deployment](#deployment)\n- [Usage](#usage)\n- [Running the Tests](#tests)\n- [Contributors](#contributors)\n\n## 🧐 About \u003ca name = \"about\"\u003e\u003c/a\u003e\n\nThe Container Registry Proxy is a small proxy for communicating with a container registry. This proxy supports plugins, these plugins implement a simple typed interface, which allows them to let the proxy modify requests in-transit.\n\n![Diagram showing how the proxy hands-off requests to plugins](docs/images/crp-usage-diagram-chainable-plugins.svg)\n\nHere's a small demo on how to use the proxy together with the build in Semantic Chaos-plugin. This plugin intercepts requests to resolve a tag to a specific container, and replaces this tag with a random tag which is within scope of the semantic versioning. In this case, the user requested tag `4`, the proxy then retrieves all tags which match `4.x.x` and returns one at-random to the user.\n\n[![Demo](https://i.imgur.com/SXidWbc.gif)](https://i.imgur.com/h9xG5ne.mp4)\n\n## 🏁 Getting Started \u003ca name = \"getting_started\"\u003e\u003c/a\u003e\n\nThese instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See [deployment](#deployment) for notes on how to deploy the project on a live system.\n\n### Prerequisites\n\nYou need to have [Yarn][yarn-install] installed to use this repository.\n\n### Installing\n\nFirst we need to install all dependencies, run:\n\n```bash\nyarn install\n```\n\n### Running Locally\n\nTo start the development environment using either of the following commands:\n\n```bash\n# Without file watching\nyarn start\n\n# With file watching\nyarn dev\n```\n\n### Running in Kubernetes using DevSpace\n\nBuild the application, the `--watch` flag is optional and enables automatic hotreloading:\n\n```bash\nyarn build --watch\n```\n\nThen to configure and launch [DevSpace](https://devspace.sh/) run:\n\n```bash\n# Configure DevSpace to the desired namespace\ndevspace use namespace container-registry-proxy\n\n# Deploy a development version onto K8s\ndevspace dev\n```\n\n## 🚀 Deployment \u003ca name = \"deployment\"\u003e\u003c/a\u003e\n\n### Automatic\n\nCurrently, the only supported method of automatically deploying this application is by using [Heroku][heroku-deploy].\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)][heroku-deploy]\n\nWhen deploying using Heroku, it is recommended to configure the application using environment variables. Make sure to redeploy the application after changing the environment variables, as to put them into effect.\n\n### Manual\n\nWe automatically build and deploy all [releases][gh-releases] to:\n\n- [NPM][crp-npm]\n- [Docker Hub][crp-hub]\n\n#### NPM\n\nInstall the application locally:\n\n```bash\n# Install globally in NPM\nnpm install -g container-registry-proxy\n\n# Install globally in Yarn\nyarn global add container-registry-proxy\n```\n\nStart the proxy:\n\n```bash\n# Full command\ncontainer-registry-proxy --help\n\n# A short name is also available\ncrp --help\n```\n\n#### Docker\n\n```bash\ndocker run --rm -it -p 8080:8080 --name crp addono/container-registry-proxy --help\n```\n\n## 🎈 Usage \u003ca name=\"usage\"\u003e\u003c/a\u003e\n\nThe default configuration of the proxy can be overwritten during startup by adding flags or environment variables:\n\n```bash\n$ container-registry-proxy start --help\nUsage: container-registry-proxy start [options]\n\nStarts the proxy server\n\nOptions:\n  --plugin \u003cname\u003e        Adds a plugin by name, can be supplied multiple times. Can also be set as a comma separated list using the PLUGINS environment variable. (default: [])\n  --customPlugin \u003cpath\u003e  Adds a custom plugin by path Can also be set as a comma separated list using the CUSTOM_PLUGINS environment variable. (default: [])\n  --port \u003cport\u003e          The port to launch the service on. Can also be set using the PORT environment variable (default: \"8080\")\n  --registry \u003chostname\u003e  The host to forward requests to. Can also be set using the REGISTRY environment variable. (default: \"registry.hub.docker.com\")\n  --http                 Fall back to using HTTP instead of HTTPS. Can also be set by setting the HTTP environment variable to \"true\". (default: false)\n  -h, --help             display help for command\n```\n\nFor example, these two methods of starting the proxy are equivalent:\n\n```bash\n# Using arguments\ncontainer-registry-proxy --plugin semanticChaos --port 8000\n\n# Using environment variables\nPLUGINS=semanticChaos PORT=8000 container-registry-proxy\n```\n\nOnce you have a proxy running, you can use it like this:\n\n```bash\n# For https://hub.docker.com/r/addono/container-registry-proxy\ndocker pull localhost:8080/addono/container-registry-proxy\n\n# For https://hub.docker.com/_/nginx\ndocker pull localhost:8080/library/nginx\n```\n\n\u003e Note: If your Docker daemon is running in a VM, which would be the case if you're using Docker Toolbox on Mac, then pulling directly from localhost will not work.\n\u003e\n\u003e One workaround is using ngrok to have a publicly available domain name to connect to. As an added benefit, this also gives HTTPS support out of the box and makes it accessible also from other machines:\n\u003e\n\u003e ```bash\n\u003e # Note the ngrok domain assigned to you\n\u003e ngrok http 8080\n\u003e\n\u003e # Make sure to replace the ngrok domain name\n\u003e docker pull 5d354ae8.ngrok.io/library/nginx\n\u003e ```\n\n### Custom Plugins\n\nCustom plugins are simple JavaScript modules implementing the [`Plugin`](./src/plugins.ts) interface, which are loaded in at runtime. An example of a custom plugin can be found [here][example-plugin] Assuming we have the `container-regsitry-proxy` installed locally and a plugin in `./dist/plugin.js`, then we can load this plugin using:\n\n```bash\ncontainer-registry-proxy --customPlugin ./dist/plugin.js\n```\n\n### Creating Custom Plugins\n\nTo create your own custom plugin, it is recommended to write it in TypeScript and compile it to JavaScript. It's easiest to fork or copy the [example plugin][example-plugin] and follow the instructions there, as it already incorporates various best-practices to ease development.\n\nAlternatively, a minimal approach on creating a plugin would follow the following steps:\n\n```bash\nyarn global add container-registry-proxy typescript\n```\n\nCreate a file `plugin.ts` with the following content:\n\n```typescript\nimport { Request, Plugin } from 'container-registry-proxy/dist/plugins'\n\nconst plugin: Plugin = {\n  name: 'Logger',\n  description: 'Merely logs all requests',\n  requestPipe: async (request: Request) =\u003e {\n    console.log('LOGGER:', request)\n    return request\n  },\n}\n\nexport default plugin\n```\n\nNow compile it into JavaScript:\n\n```bash\ntsc plugin.ts\n```\n\nNow, the plugin can be used by running:\n\n```bash\ncontainer-registry-proxy --customPlugin plugin.js\n```\n\n## 🔧 Running the Tests \u003ca name = \"tests\"\u003e\u003c/a\u003e\n\nAfter setting up the development environment, tests can be invoked using:\n\n```bash\nyarn test\n```\n\n## ✨ Contributors \u003ca name = \"contributors\"\u003e\u003c/a\u003e\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://aknapen.nl\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/15435678?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAdriaan Knapen\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/Addono/container-registry-proxy/commits?author=Addono\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/Addono/container-registry-proxy/commits?author=Addono\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n\n[crp-depfu]: https://depfu.com/github/Addono/container-registry-proxy?project_id=12599\n[crp-hub]: https://hub.docker.com/r/addono/container-registry-proxy\n[crp-npm]: https://www.npmjs.com/package/container-registry-proxy\n[example-plugin]: https://github.com/Addono/container-registry-proxy-custom-plugin-example\n[gh-stars]: https://github.com/Addono/container-registry-proxy/stargazers\n[gh-releases]: https://github.com/Addono/container-registry-proxy/releases\n[gh-license]: https://github.com/Addono/container-registry-proxy/blob/master/LICENSE\n[heroku-deploy]: https://heroku.com/deploy?template=https://github.com/addono/container-registry-proxy/tree/master\n[yarn-install]: https://yarnpkg.com/en/docs/install\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faddono%2Fcontainer-registry-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faddono%2Fcontainer-registry-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faddono%2Fcontainer-registry-proxy/lists"}