IPDR is a Docker Registry tool that proxies Docker registry requests to IPFS for pushing and pulling images. IPDR allows you to store Docker images on IPFS instead of a central registry like Docker Hub or Google Container Registry. Docker images are referenced by their IPFS hash instead of the repo tag names.
IPDR is compatabile with the Docker Registry HTTP API V2 Spec for pulling images*
*not fully 1:1 implemented yet
High-level overview:
-
Install with Go:
go get -u github.com/ipdr/ipdr/cmd/ipdr
-
Install from release binaries:
# replace x.x.x with the latest version wget https://github.com/ipdr/ipdr/releases/download/x.x.x/ipdr_x.x.x_linux_amd64.tar.gz tar -xvzf ipdr_x.x.x_linux_amd64.tar.gz ipdr ./ipdr --help # move to bin path sudo mv ipdr /usr/local/bin/ipdr
-
Start IPFS daemon (Install instructions):
$ ipfs daemon Initializing daemon... Swarm listening on /ip4/127.0.0.1/tcp/4001 Swarm listening on /ip4/192.168.86.90/tcp/4001 Swarm listening on /ip6/::1/tcp/4001 Swarm listening on /p2p-circuit/ipfs/QmR29wrbNv3WrMuodwuLiDwvskuZKKeTtcYDw7SwNffzCH Swarm announcing /ip4/127.0.0.1/tcp/4001 Swarm announcing /ip4/192.168.0.21/tcp/43042 Swarm announcing /ip4/192.168.86.90/tcp/4001 Swarm announcing /ip6/::1/tcp/4001 API server listening on /ip4/0.0.0.0/tcp/5001 Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080 Daemon is ready
-
Add
docker.localto/etc/hosts:echo '127.0.0.1 docker.local' | sudo tee -a /etc/hosts echo '::1 docker.local' | sudo tee -a /etc/hosts
-
Flush local DNS cache:
-
on macOS:
dscacheutil -flushcache; sudo killall -HUP mDNSResponder -
on Ubuntu 18+:
sudo systemd-resolve --flush-caches
-
-
-
Create
Dockerfile:FROM busybox:latest CMD echo 'hello world'
-
Build Docker image:
docker build -t example/helloworld .Test run:
$ docker run example/helloworld:latest hello world
-
Use IPDR CLI to push to IPFS:
$ ipdr push example/helloworld INFO[0000] [registry] temp: /var/folders/k1/m2rmftgd48q97pj0xf9csdb00000gn/T/205139235 INFO[0000] [registry] preparing image in: /var/folders/k1/m2rmftgd48q97pj0xf9csdb00000gn/T/657143846 INFO[0000] [registry] dist: /var/folders/k1/m2rmftgd48q97pj0xf9csdb00000gn/T/657143846/default/blobs/sha256:305510b2c684403553fd8f383e8d109b147df2cfde60e40a85564532c383c8b8 INFO[0000] [registry] compressing layer: /var/folders/k1/m2rmftgd48q97pj0xf9csdb00000gn/T/205139235/886f4bdfa483cc176e947c63d069579785c051793a9634f571fded7b9026cd3c/layer.tar INFO[0000] [registry] root dir: /var/folders/k1/m2rmftgd48q97pj0xf9csdb00000gn/T/657143846 INFO[0000] [registry] upload hash QmRxZ5Wffj6b1j8ckJLcr7yFrbHUhBYXsAMbj7Krwu1pp8 INFO[0000] [registry] uploaded to /ipfs/Qmc2ot2NQadXmbvPbsidyjYDvPfPwKZmovzNpfRPKxXUrL INFO[0000] [registry] docker image ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi Successfully pushed Docker image to IPFS: /ipfs/Qmc2ot2NQadXmbvPbsidyjYDvPfPwKZmovzNpfRPKxXUrL -
Use IPDR CLI to pull from IPFS:
$ ipdr pull /ipfs/QmagW4H1uE5rkm8A6iVS8WuiyjcWQzqXRHbM3KuUfzrCup INFO[0000] [registry/server] port 5000 INFO[0000] [registry] attempting to pull docker.local:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi INFO[0000] [registry/server] /v2/ INFO[0000] [registry/server] /v2/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi/manifests/latest INFO[0000] [registry/server] location http://127.0.0.1:8080/ipfs/Qmc2ot2NQadXmbvPbsidyjYDvPfPwKZmovzNpfRPKxXUrL/manifests/latest-v2 {"status":"Pulling from ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi","id":"latest"} {"status":"Digest: sha256:1fb36e4704d6ebad5becdcfe996807de5f8db687da396330f112157c888c165b"} {"status":"Status: Downloaded newer image for docker.local:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi:latest"} Successfully pulled Docker image from IPFS: docker.local:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi -
Run image pulled from IPFS:
$ docker run docker.local:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi hello world
-
Retag Docker image:
$ docker tag docker.local:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi example/helloworld:latest
-
We can also pull the image using
docker pull:-
First run the IPDR server in a seperate terminal:
$ ipdr server -p 5000 INFO[0000] [registry/server] listening on [::]:5000
-
Then convert the IPFS hash to a valid format docker allows:
$ ipdr convert QmYMg6WAuvF5i5yFmjT8KkqewZ5Ngh4U9Mp1bGfdjraFVk --format=docker ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y
-
Now we can
docker pullthe image from IPFS:$ docker pull docker.local:5000/ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y Using default tag: latest latest: Pulling from ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y Digest: sha256:6b787c9e04c2038d4b3cb0392417abdddfcfd88e10005d970fc751cdcfd6d895 Status: Downloaded newer image for docker.local:5000/ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y:latestTest run:
$ docker run docker.local:5000/ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y hello world
-
# build Docker image
docker build -t example/helloworld .
# push to IPFS
IPFS_HASH="$(ipdr push example/helloworld --silent)"
# pull from IPFS
REPO_TAG=$(ipdr pull "$IPFS_HASH" --silent)
# run image pulled from IPFS
docker run "$REPO_TAG"$ ipdr --help
The command-line interface for the InterPlanetary Docker Registry.
More info: https://github.com/ipdr/ipdr
Usage:
ipdr [flags]
ipdr [command]
Available Commands:
convert Convert a hash to IPFS format or Docker registry format
help Help about any command
pull Pull image from the IPFS-backed Docker registry
push Push image to IPFS-backed Docker registry
server Start IPFS-backed Docker registry server
Flags:
-h, --help help for ipdr
Use "ipdr [command] --help" for more information about a command.An example of using IPNS to resolve image tag names.
- First start local server:
ipdr server -p 5000- Tag the image:
docker pull hello-world
docker tag hello-world docker.local:5000/hello-world- Push to local registry:
docker push --quiet docker.local:5000/hello-worldCID mappings live under ~/.ipdr
$ tree ~/.ipdr/
/home/username/.ipdr/
└── cids
└── hello-world
└── latest- Add cids directory to IPFS:
$ ipfs add -r ~/.ipdr/cids/ --quieter
QmVtjwa3kdFJHce2wnFuygaCHdSPXraBd4FRSEZKjqZWQp- Set
_dnslinkTXT record on the domain to point to the directory IPFS hash:
dnslink=/ipfs/QmVtjwa3kdFJHce2wnFuygaCHdSPXraBd4FRSEZKjqZWQp
- Verify DNS changes:
$ dig _dnslink.example.com -t TXT +short
"dnslink=/ipfs/QmVtjwa3kdFJHce2wnFuygaCHdSPXraBd4FRSEZKjqZWQp"- Re-run server, now with domain as resolver:
$ ipdr server --cid-resolver=example.com- Now we can run ipdr dig to get CID using repo tag name!
$ ipdr dig hello-world:latest
bafybeiakvswzlopeu573372p5xry47tkc2hhcg5q5rulmbfrnkecrbnt3yNote: if nothing is returned, then make sure the IPFS gateway is correct.
- Next pull and the docker image from IPFS using the resolved CID formatted for docker:
docker pull docker.local:5000/bafybeiakvswzlopeu573372p5xry47tkc2hhcg5q5rulmbfrnkecrbnt3y
docker run docker.local:5000/bafybeiakvswzlopeu573372p5xry47tkc2hhcg5q5rulmbfrnkecrbnt3ymake test-
Q: How do I configure the local registry host or port that IPDR uses when pushing or pulling Docker images?
- A: Use the
--docker-registry-hostflag, eg.--docker-registry-host docker.for.mac.local:5000
- A: Use the
-
Q: How do I configure the IPFS host that IPDR uses for pushing Docker images?
- A: Use the
--ipfs-hostflag, eg.--ipfs-host 127.0.0.1:5001
- A: Use the
-
Q: How do I configure the IPFS gateway that IPDR uses for pulling Docker images?
- A: Use the
--ipfs-gatewayflag, eg.--ipfs-gateway https://ipfs.io
- A: Use the
-
Q: How can I configure the port for the IPDR registry server?
- A: Use the
--portflag, eg.--port 5000
- A: Use the
-
Q: How do I setup HTTPS/TLS on the IPDR registry server?
- A: Use the
--tlsKeyPathand--tlsCertPathflag, eg.--tlsKeyPath path/server.key --tlsCertPath path/server.crt
- A: Use the
-
Q: How do I get
docker.localto work?- A: Make sure to add
127.0.0.1 docker.localto/etc/hosts. Optionally, you may uselocal.ipdr.iowhich resolves to127.0.0.1
- A: Make sure to add
Pull requests are welcome!
For contributions please create a new branch and submit a pull request for review.
Many thanks to @qiangli and all the contributors that made this package better.
- Discuss on Discord
Released under the MIT license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent