{"id":28962296,"url":"https://github.com/psviderski/unregistry","last_synced_at":"2025-10-24T07:02:06.618Z","repository":{"id":299909553,"uuid":"995113401","full_name":"psviderski/unregistry","owner":"psviderski","description":"Push docker images directly to remote servers without an external registry","archived":false,"fork":false,"pushed_at":"2025-06-18T22:53:55.000Z","size":12536,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-18T23:29:14.687Z","etag":null,"topics":["containerd","docker","golang","kubernetes","oci","registry"],"latest_commit_sha":null,"homepage":"","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/psviderski.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-03T01:48:51.000Z","updated_at":"2025-06-18T22:53:54.000Z","dependencies_parsed_at":"2025-06-18T23:40:20.013Z","dependency_job_id":null,"html_url":"https://github.com/psviderski/unregistry","commit_stats":null,"previous_names":["psviderski/unregistry"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/psviderski/unregistry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psviderski%2Funregistry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psviderski%2Funregistry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psviderski%2Funregistry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psviderski%2Funregistry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/psviderski","download_url":"https://codeload.github.com/psviderski/unregistry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/psviderski%2Funregistry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261595647,"owners_count":23182240,"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":["containerd","docker","golang","kubernetes","oci","registry"],"created_at":"2025-06-24T03:01:47.332Z","updated_at":"2025-10-24T07:02:06.585Z","avatar_url":"https://github.com/psviderski.png","language":"Go","funding_links":["https://github.com/sponsors/psviderski"],"categories":["Go","kubernetes","语音识别与合成_其他","docker","DevOps"],"sub_categories":["资源传输下载","Selfhosted"],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\".github/images/logo-light.svg#gh-light-mode-only\" alt=\"Unregistry logo\"/\u003e\n  \u003cimg src=\".github/images/logo-dark.svg#gh-dark-mode-only\" alt=\"Unregistry logo\"/\u003e\n  \u003cp\u003e\u003cstrong\u003e▸ Push docker images directly to remote servers without an external registry ◂\u003c/strong\u003e\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://discord.gg/eR35KQJhPu\"\u003e\u003cimg src=\"https://img.shields.io/badge/discord-5865F2.svg?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Join Discord\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://x.com/psviderski\"\u003e\u003cimg src=\"https://img.shields.io/badge/follow-black?style=for-the-badge\u0026logo=X\u0026logoColor=while\" alt=\"Follow on X\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/sponsors/psviderski\"\u003e\u003cimg src=\"https://img.shields.io/badge/Donate-EA4AAA.svg?style=for-the-badge\u0026logo=githubsponsors\u0026logoColor=white\" alt=\"Donate\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nUnregistry is a lightweight container image registry that stores and serves images directly from your Docker daemon's\nstorage.\n\nThe included `docker pussh` command (extra 's' for SSH) lets you push images straight to remote Docker servers over SSH.\nIt transfers only the missing layers, making it fast and efficient.\n\nhttps://github.com/user-attachments/assets/9d704b87-8e0d-4c8a-9544-17d4c63bd050\n\n## The problem\n\nYou've built a Docker image locally. Now you need it on your server. Your options suck:\n\n- **Docker Hub / GitHub Container Registry** - Your code is now public, or you're paying for private repos\n- **Self-hosted registry** - Another service to maintain, secure, and pay for storage\n- **Save/Load** - `docker save | ssh \u003cremote server\u003e docker load` transfers the entire image, even if 90% already exists\n  on the server\n- **Rebuild remotely** - Wastes time and server resources. Plus now you're debugging why the build fails in production\n\nYou just want to move an image from A to B. Why is this so hard?\n\n## The solution\n\n```shell\ndocker pussh myapp:latest user@server\n```\n\nThat's it. Your image is on the remote server. No registry setup, no subscription, no intermediate storage, no exposed\nports. Just a **direct transfer** of the **missing layers** over SSH.\n\nHere's what happens under the hood:\n\n1. Establishes SSH tunnel to the remote server\n2. Starts a temporary unregistry container on the server\n3. Forwards a random localhost port to the unregistry port over the tunnel\n4. `docker push` to unregistry through the forwarded port, transferring only the layers that don't already exist\n   remotely. The transferred image is instantly available on the remote Docker daemon\n5. Stops the unregistry container and closes the SSH tunnel\n\nIt's like `rsync` for Docker images — simple and efficient.\n\n\u003e [!NOTE]\n\u003e Unregistry was created for [Uncloud](https://github.com/psviderski/uncloud), a lightweight tool for deploying\n\u003e containers across multiple Docker hosts. We needed something simpler than a full registry but more efficient than\n\u003e save/load.\n\n## Requirements\n\n### On local machine\n\n- Docker CLI with plugin support (Docker 19.03+)\n- OpenSSH client\n\n### On remote server\n\n- Docker is installed and running\n- SSH user has permissions to run `docker` commands (user is `root` or non-root user is in `docker` group — see\n  [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)\n  for details)\n- If `sudo` is required, ensure the user can run `sudo docker` without a password prompt\n- Your server has internet access to [ghcr.io](https://ghcr.io) to pull the unregistry image\n  `ghcr.io/psviderski/unregistry:latest` on first `docker pussh` use.\n    - If your server requires a proxy to access the internet, configure Docker to use it by following the\n      [Daemon proxy configuration](https://docs.docker.com/engine/daemon/proxy/) guide.\n    - For air-gapped environments or where the access to [ghcr.io](https://ghcr.io) is restricted, you can preload the\n      image manually:\n      ```shell\n      # Get the needed unregistry image version from the plugin version output\n      docker pussh --version\n      # Will return:\n      #   ...\n      #   unregistry image: ghcr.io/psviderski/unregistry:X.Y.Z\n\n      # On a machine with internet access\n      docker pull ghcr.io/psviderski/unregistry:X.Y.Z\n      docker save ghcr.io/psviderski/unregistry:X.Y.Z | ssh user@server docker load\n      ```\n- Unregistry container requires access to the containerd socket at `/run/containerd/containerd.sock`, so the container\n  runs as `root` to have the necessary permissions\n\n## Installation\n\n### macOS/Linux via Homebrew\n\n```shell\nbrew install psviderski/tap/docker-pussh\n```\n\nAfter installation, to use `docker-pussh` as a Docker CLI plugin (`docker pussh` command) you need to create a symlink:\n\n```shell\nmkdir -p ~/.docker/cli-plugins\nln -sf $(brew --prefix)/bin/docker-pussh ~/.docker/cli-plugins/docker-pussh\n```\n\n### macOS/Linux via direct download\n\nDownload the current version:\n\n```shell\nmkdir -p ~/.docker/cli-plugins\n\n# Download the script to the docker plugins directory\ncurl -sSL https://raw.githubusercontent.com/psviderski/unregistry/v0.3.1/docker-pussh \\\n  -o ~/.docker/cli-plugins/docker-pussh\n\n# Make it executable\nchmod +x ~/.docker/cli-plugins/docker-pussh\n```\n\nIf you want to download and use the latest version from the main branch:\n\n```shell\ncurl -sSL https://raw.githubusercontent.com/psviderski/unregistry/main/docker-pussh \\\n  -o ~/.docker/cli-plugins/docker-pussh\nchmod +x ~/.docker/cli-plugins/docker-pussh\n```\n\n### Debian\n\nVia unofficial repository packages created and maintained\nat [unregistry-debian](https://github.com/dariogriffo/unregistry-debian/) by @dariogriffo\n\nYou can install unregistry the debian way by running:\n\n```sh\ncurl -sS https://debian.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/debian.griffo.io.gpg\necho \"deb https://debian.griffo.io/apt $(lsb_release -sc 2\u003e/dev/null) main\" | sudo tee /etc/apt/sources.list.d/debian.griffo.io.list\napt install -y unregistry\napt install docker-pussh\n```\n\nor in the releases page of the repository [here](https://github.com/dariogriffo/unregistry-debian/releases)\n\n### Windows\n\nWindows is not currently supported, but you can try using [WSL 2](https://docs.docker.com/desktop/features/wsl/)\nwith the above Linux instructions.\n\n### Verify installation\n\n```shell\ndocker pussh --help\n```\n\n## ⚠️ Containerd image store configuration\n\nUnregistry stores images directly in containerd's image store, which is the underlying container runtime used by Docker.\nHowever, by default, Docker maintains its own separate storage layer and doesn't directly use images from containerd.\n\nWhen you enable [containerd image store](https://docs.docker.com/engine/storage/containerd/) in Docker, it allows Docker\nto directly use the same images that unregistry stores in containerd, eliminating duplication.\n\n### With containerd image store enabled (recommended)\n\n- Images pushed through unregistry are immediately available to Docker\n- No additional storage space is used (images are stored once in containerd)\n- Faster `pussh` operations without the additional pull step from unregistry to the classic Docker image store\n\n### Without containerd image store (default Docker behaviour)\n\n- After pushing, `pussh` runs an additional `docker pull` on the remote host to pull the image from unregistry to make\n  it available to Docker\n- Images are stored twice: once in containerd (by unregistry) and once in the classic Docker image store\n- These unmanaged images in containerd can fill up disk space over time. To manage them manually, use:\n  ```shell\n  sudo ctr -n moby images ls\n  sudo ctr -n moby images rm \u003cimage\u003e\n  ```\n\n### How to enable containerd image store\n\nPlease refer to the official Docker documentation:\n[Enable containerd image store on Docker Engine](https://docs.docker.com/engine/storage/containerd/#enable-containerd-image-store-on-docker-engine).\n\n\u003e [!WARNING]\n\u003e Switching to containerd image store causes you to temporarily lose images and containers created using the classic\n\u003e storage driver. Those resources still exist on your filesystem, and you can retrieve them by turning off the\n\u003e containerd image store feature.\n\n## Usage\n\nPush an image to a remote server. Please make sure the SSH user has permissions to run `docker` commands (user is\n`root` or non-root user is in `docker` group). If `sudo` is required, ensure the user can run `sudo docker` without a\npassword prompt.\n\n```shell\ndocker pussh myapp:latest user@server.example.com\n```\n\nWith SSH key authentication if the private key is not added to your SSH agent:\n\n```shell\ndocker pussh myapp:latest ubuntu@192.168.1.100 -i ~/.ssh/id_rsa\n```\n\nUsing a custom SSH port:\n\n```shell\ndocker pussh myapp:latest user@server:2222\n```\n\nPush a specific platform for a multi-platform image. The local Docker has to use\n[containerd image store](https://docs.docker.com/desktop/features/containerd/) to support multi-platform images.\n\n```shell\ndocker pussh myapp:latest user@server --platform linux/amd64\n```\n\nUse a specific unregistry image version on the remote host:\n\n```shell\nUNREGISTRY_IMAGE=ghcr.io/psviderski/unregistry:A.B.C docker pussh myapp:latest user@server.example.com\n```\n\n## Use cases\n\n### Deploy to production servers\n\nBuild locally and push directly to your production servers. No middleman.\n\n```shell\ndocker build --platform linux/amd64 -t myapp:1.2.3 .\ndocker pussh myapp:1.2.3 deploy@prod-server\nssh deploy@prod-server docker run -d myapp:1.2.3\n```\n\n### CI/CD pipelines\n\nSkip the registry complexity in your pipelines. Build and push directly to deployment targets.\n\n```yaml\n- name: Build and deploy\n  run: |\n    docker build -t myapp:${{ github.sha }} .\n    docker pussh myapp:${{ github.sha }} deploy@staging-server\n```\n\n### Homelab and air-gapped environments\n\nDistribute images in isolated networks that can't access public registries over the internet.\n\n## Advanced usage\n\n### Running unregistry standalone\n\nSometimes you want a local registry without the overhead. Unregistry works great for this:\n\n```shell\n# Run unregistry locally and expose it on port 5000\ndocker run -d -p 5000:5000 --name unregistry \\\n  -v /run/containerd/containerd.sock:/run/containerd/containerd.sock \\\n  ghcr.io/psviderski/unregistry\n\n# Use it like any registry\ndocker tag myapp:latest localhost:5000/myapp:latest\ndocker push localhost:5000/myapp:latest\n```\n\n### Custom SSH options\n\nNeed custom SSH settings? Use the standard SSH config file:\n\n```shell\n# ~/.ssh/config\nHost prod-server\n    HostName server.example.com\n    User deploy\n    Port 2222\n    IdentityFile ~/.ssh/deploy_key\n\n# Now just use\ndocker pussh myapp:latest prod-server\n```\n\n## Third-party projects\n\n- https://github.com/SonOfBytes/unregistry-action - GitHub Action to push Docker images to remote servers using\n  `docker-pussh` plugin for Docker CLI\n- https://github.com/RezaKargar/setup-unregistry - GitHub Action to install `docker-pussh` plugin for Docker CLI\n\n## Contributing\n\nFound a bug or have a feature idea? We'd love your help!\n\n- 🐛 Found a bug? [Open an issue](https://github.com/psviderski/unregistry/issues)\n\n* 💡 Have questions, ideas, or need help?\n    * Start a discussion or join an existing one in\n      the [Discussions](https://github.com/psviderski/unregistry/discussions).\n    * Join the [Uncloud Discord community](https://discord.gg/eR35KQJhPu) where we discuss features, roadmap,\n      implementation details, and help each other out.\n\n## Inspiration \u0026 acknowledgements\n\n- [Spegel](https://github.com/spegel-org/spegel) - P2P container image registry that inspired me to implement a registry\n  that uses containerd image store as a backend.\n- [Docker Distribution](https://github.com/distribution/distribution) - the bulletproof Docker registry implementation\n  that unregistry is based on.\n\n##\n\n\u003cdiv align=\"center\"\u003e\n  Built with ❤️ by \u003ca href=\"https://github.com/psviderski\"\u003ePasha Sviderski\u003c/a\u003e who just wanted to deploy his images\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsviderski%2Funregistry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpsviderski%2Funregistry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpsviderski%2Funregistry/lists"}