Configure Docker to use Pyrsia
Once you've completed the installation, it's time to configure your build tools to make use of Pyrsia.
In this tutorial we will show how you can easily modify your Docker setup to use Pyrsia to download official Docker images.
First, make sure to complete the steps in the installation tutorial.
Next, configure your Docker installation to use Pyrsia as a registry mirror.
On Windows or macOS, open your Docker Desktop -> Settings -> Docker Engine where Docker allows you to set registry-mirrors. Configure your node as a registry mirror by adding/editing the following in the configuration:
On Linux, you'll find this configuration in the file
If you've run the apt installation, this step was already automatically
performed for you.
Why 0.0.0.0? \ In general you would specify
localhost:7888as the registry mirror but on MacOS and Windows this won't work because Docker Engine is running in a VM, which is not the same as the local host your Pyrsia is running on. Using
0.0.0.0works around this issue. In case you're having issues, try specifying your host IP address as the registry-mirror and bind your local Pyrsia node to that IP (using
-Hwith an explicit IP address or using
You will need to restart Docker Desktop. Once restarted you should be able to pull Docker images through Pyrsia.
Pull a docker image
alpine:3.16.2 as an example. Your Docker installation is now configured
to use your local Pyrsia node to retrieve artifacts. When you start Pyrsia, it will
make sure it has the most recent copy of the blockchain, which contains all the
publication logs, also known as transparency logs.
When your Docker client pulls an image, it will make the request to your local Pyrsia node (because you configured it as a registry mirror) and it will fetch the artifact from a peer node in the Pyrsia network, verify it based on the transparency logs and return it to the Docker client.
Let's try this, but first make sure Alpine is not yet in your local Docker cache:
docker rmi alpine:3.16.2
Then pull the image:
docker pull alpine:3.16.2
Congratulations! The alpine Docker image was now retrieved from the Pyrsia network.
You can verify this in the Pyrsia logs. On Linux you will find the logs in
On Windows you can see the logs in the command prompt you used to run the Pyrsia node.
You will see something like this:
DEBUG pyrsia::docker::v2::handlers::manifests > Fetching manifest for alpine with tag: 3.16
INFO pyrsia::artifact_service::storage > An artifact is being pulled from the artifact manager b0ed9f25-f322-47ef-8dac-03154209cfcf
Note: On macOS or Windows, you can also see the Pyrsia logs, but it depends on your specific installation where to find them. (See Installation tutorial)
If you would repeat these steps, your local Pyrsia node will already have a copy of the requested artifact, so it won't be retrieved again:
This local cache is also used by your Pyrsia node to participate in the artifact distribution to other nodes.
TODO: document how a user can configure the Pyrsia node to limit the bandwidth used or to disable its participation in content distribution altogether.
Inspect the Pyrsia transparency log
Now, let's take a look at the transparency logs.
If you ran through all the steps of the installation tutorial, the Pyrsia CLI tool will be available.
You can use this CLI tool to configure your local Pyrsia node, but also to inspect the transparency logs for a given artifact.
If you have started your Pyrsia node with default settings, you can skip this step. Otherwise configure the CLI tool with your required settings:
pyrsia config --edit
And enter the correct values:
Enter disk space to be allocated to pyrsia(Please enter with units ex: 10 GB):
Node configuration Saved !!
Next, let's take the
alpine:3.16.2 example again:
pyrsia inspect-log docker --image alpine:3.16.2
This CLI command returns the transparency logs for all the Pyrsia artifacts that
make up the Docker image
Requesting a build
While it's Pyrsia intention to build and publish all official Docker images, there is a possibility that a Docker image is not yet built/available.
When you pull an image that is unknown, your local Pyrsia node will send a build request to one of the authorized build nodes, which schedules a build for the given Docker image.
Your Docker client will receive an error from Pyrsia at that point (your local Docker client might fall back to Docker Hub), but when the build is finished and the other build nodes inside the Pyrsia network reached consensus, your node will receive updated transparency logs via the blockchain and you will be able to pull the image from the Pyrsia network.
To find out if an image is available, use the
inspect-log described above.
Alternatively, you can also explicitly request the build of a new Docker image:
pyrsia build docker --image alpine:3.16.3
This will send the build request to one of the authorized build nodes, which will start a build. When consensus about that build is reached, it will be available in the transparency logs and can be retrieved by all nodes in the network.