🐋 IPFS-backed Docker Registry
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.local
to /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 pull
the 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:latest
Test 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.
ipdr server -p 5000
docker pull hello-world
docker tag hello-world docker.local:5000/hello-world
docker push --quiet docker.local:5000/hello-world
CID mappings live under ~/.ipdr
$ tree ~/.ipdr/
/home/username/.ipdr/
└── cids
└── hello-world
└── latest
$ ipfs add -r ~/.ipdr/cids/ --quieter
QmVtjwa3kdFJHce2wnFuygaCHdSPXraBd4FRSEZKjqZWQp
_dnslink
TXT record on the domain to point to the directory IPFS hash:dnslink=/ipfs/QmVtjwa3kdFJHce2wnFuygaCHdSPXraBd4FRSEZKjqZWQp
$ dig _dnslink.example.com -t TXT +short
"dnslink=/ipfs/QmVtjwa3kdFJHce2wnFuygaCHdSPXraBd4FRSEZKjqZWQp"
$ ipdr server --cid-resolver=example.com
$ ipdr dig hello-world:latest
bafybeiakvswzlopeu573372p5xry47tkc2hhcg5q5rulmbfrnkecrbnt3y
Note: if nothing is returned, then make sure the IPFS gateway is correct.
docker pull docker.local:5000/bafybeiakvswzlopeu573372p5xry47tkc2hhcg5q5rulmbfrnkecrbnt3y
docker run docker.local:5000/bafybeiakvswzlopeu573372p5xry47tkc2hhcg5q5rulmbfrnkecrbnt3y
make test
Q: How do I configure the local registry host or port that IPDR uses when pushing or pulling Docker images?
--docker-registry-host
flag, eg. --docker-registry-host docker.for.mac.local:5000
Q: How do I configure the IPFS host that IPDR uses for pushing Docker images?
--ipfs-host
flag, eg. --ipfs-host 127.0.0.1:5001
Q: How do I configure the IPFS gateway that IPDR uses for pulling Docker images?
--ipfs-gateway
flag, eg. --ipfs-gateway https://ipfs.io
Q: How can I configure the port for the IPDR registry server?
--port
flag, eg. --port 5000
Q: How do I setup HTTPS/TLS on the IPDR registry server?
--tlsKeyPath
and --tlsCertPath
flag, eg. --tlsKeyPath path/server.key --tlsCertPath path/server.crt
Q: How do I get docker.local
to work?
127.0.0.1 docker.local
to /etc/hosts
. Optionally, you may use local.ipdr.io
which resolves to 127.0.0.1
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.
Released under the MIT license.