Skip to content
IPFS-backed Docker Registry
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci [circleci] run ipfs daemon offline Mar 7, 2019
cmd/ipdr ipfs gateway url option Feb 18, 2019
docker fix docker package Mar 7, 2019
ipfs fix docker package Mar 7, 2019
netutil fix tests Feb 16, 2019
registry clean up log Mar 6, 2019
regutil conver cli util Feb 16, 2019
server diagram Feb 18, 2019
LICENSE initial implementation Feb 16, 2019
Makefile [readme] add to hosts command Mar 7, 2019
go.mod fix docker package Mar 7, 2019
go.sum fix docker package Mar 7, 2019


IPDR: InterPlanetary Docker Registry

IPFS-backed Docker Registry

License CircleCI Go Report Card GoDoc stability-experimental PRs Welcome

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
  • Install from release binaries:

    # replace x.x.x with the latest version
    tar -xvzf ipdr_x.x.x_linux_amd64.tar.gz ipdr
    ./ipdr --help
    # move to bin path
    sudo mv ipdr /usr/local/bin/ipdr

Getting started


  • Start IPFS daemon (Install instructions):

    $ ipfs daemon
    Initializing daemon...
    Swarm listening on /ip4/
    Swarm listening on /ip4/
    Swarm listening on /ip6/::1/tcp/4001
    Swarm listening on /p2p-circuit/ipfs/QmR29wrbNv3WrMuodwuLiDwvskuZKKeTtcYDw7SwNffzCH
    Swarm announcing /ip4/
    Swarm announcing /ip4/
    Swarm announcing /ip4/
    Swarm announcing /ip6/::1/tcp/4001
    API server listening on /ip4/
    Gateway (readonly) server listening on /ip4/
    Daemon is ready
  • Add docker.localhost to /etc/hosts:

    echo ' docker.localhost' | 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

Example flow

  • 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
    [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
    [registry] uploaded to /ipfs/Qmc2ot2NQadXmbvPbsidyjYDvPfPwKZmovzNpfRPKxXUrL
    INFO[0000] [registry] docker image ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi
    Successfully pushed Docker image to IPFS:
  • Use IPDR CLI to pull from IPFS:

    $ ipdr pull /ipfs/QmagW4H1uE5rkm8A6iVS8WuiyjcWQzqXRHbM3KuUfzrCup
    INFO[0000] [registry/server] port 5000
    INFO[0000] [registry] attempting to pull docker.localhost:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi
    INFO[0000] [registry/server] /v2/
    INFO[0000] [registry/server] /v2/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi/manifests/latest
    INFO[0000] [registry/server] location
    {"status":"Pulling from ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi","id":"latest"}
    {"status":"Digest: sha256:1fb36e4704d6ebad5becdcfe996807de5f8db687da396330f112157c888c165b"}
    {"status":"Status: Downloaded newer image for docker.localhost:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi:latest"}
    Successfully pulled Docker image from IPFS:
  • Run image pulled from IPFS:

    $ docker run docker.localhost:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi
    hello world
  • Retag Docker image:

    $ docker tag docker.localhost:5000/ciqmw4mig2uwaygddjlutoywq43udutvdmuxkcxvetsjp2mjdde27wi example/helloworld:latest
  • You 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
    • Now you can docker pull the image from IPFS:

      $ docker pull docker.localhost:5000/ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y
      Using default tag: latest
      latest: Pulling from ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y
      Digest: sha256:6b787c9e04c2038d4b3cb0392417abdddfcfd88e10005d970fc751cdcfd6d895
      Status: Downloaded newer image for docker.localhost:5000/ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y:latest

      Test run:

      $ docker run docker.localhost:5000/ciqjjwaeoszdgcaasxmlhjuqnhbctgwijqz64w564lrzeyjezcvbj4y
      hello world

TLDR; example

# 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:

  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

  -h, --help   help for ipdr

Use "ipdr [command] --help" for more information about a command.


make test


  • Q: How can I configure the local registry host or port that IPDR uses when pushing or pulling Docker images?

    • A: Use the --docker-registry-host flag, eg. --docker-registry-host docker.for.mac.local:5000
  • Q: How can I configure the IPFS host that IPDR uses for pushing Docker images?

    • A: Use the --ipfs-host flag, eg. --ipfs-host
  • Q: How can I configure the IPFS gateway that IPDR uses for pulling Docker images?

    • A: Use the --ipfs-gateway flag, eg. --ipfs-gateway
  • Q: How can I configure the port for the IPDR registry server?

    • A: Use the --port flag, eg. --port 5000


Pull requests are welcome!

For contributions please create a new branch and submit a pull request for review.




You can’t perform that action at this time.