Introducing Official Algod Docker Containers

March 17, 2023

The Algorand team is pleased to announce the support for official Algod docker containers with the release of go-algorand 3.15.0.

Our Algod containers offer another method of installing and running an Algorand node – they fast-track the experience of starting and configuring any type of node, testing out dApps on a local network, and deploying smart contracts to any Algorand public network.

By containerizing Algod, you’ll reap benefits like high portability, consistent application behavior, and deployment scalability. Our container adds further pizzazz to those benefits. With just one CLI command (see example below), you’ll be able to streamline your workflow when running an Algod node by:

Spinning up a preconfigured containerized Algorand node in a matter of seconds
Fast catch up immediately started on your node, if specified
Connecting to any Algorand public network
Simplifying a developer node set-up:
- Enabling a private network environment
- Easy ability to enable Dev Mode
- Easy ability to start KMD

Technical documentation on how to deploy an Algod docker container can be found on our DockerHub here.

Container Image Tagging

The Algorand team builds multiple container images with a single Dockerfile using multistage builds. As a result, our Algorand/Algod DockerHub repository contains multiple tags.

For public network usage, the following images should be used:

algorand/algod:latest
- Represents the latest stable release version of Algod
algorand/algod:{version}-stable
- Represents the stable version of Algod at a specific version number

As a hardcore #algofam member, you can also access features that our team has been working on (note: experimenting with these features should be done on a private network, not a public one) by pulling the algorand/algod:feature-{branch} image.

Forward and onward

Supporting an official Algod container is a step forward in our mission to make Algorand the most accessible blockchain in the market. But we are not stopping there - we’re considering introducing additional tools that will simplify large-scale Algod deployments, such as:

Configuration profiles for Algod nodes
Official Algod Helm Charts
Algod Ansible Roles

If these tools are of interest, we welcome you to share your thoughts and suggestions with us on Github or in the #node-runners channel on the Algorand Discord server. We hope you join us in empowering the #algofam with even more powerful tools onwards!

Can I get a “how-to”?

Let’s look at an example of how our container can be used against our public networks.

Prerequisites:

Docker client software is installed on the target machine

Running the container:

We can launch a simple containerized Algod node on one of our networks (mainnet in this example) with fast catch-up enabled by issuing:

docker run --rm -d \
    -e NETWORK=mainnet \
    -e FAST_CATCHUP=1 \
    --name mainnet-container \
    algorand/algod:latest

Success! You are now running an Algod node on mainnet. You can check your Algod container status by executing:

docker ps

This should return the Container ID with the image name and the ports being used. If those results are lackluster, you can execute a sanity check by:

docker exec -it mainnet-container goal node status

This will return all information regarding the status of the node.

“But, what if I want to persist my blockchain data?”

Fear not, persisting your node data is possible. Let’s try that out by initializing our container again with a mounted volume by executing

docker volume create algod-data

to explicitly create a docker volume, and then initializing your node with the created algod-data volume through:

docker run --rm -d \
    -e NETWORK=mainnet \
    -e FAST_CATCHUP=1 \
    -v algod-data:/algod/data
    --name mainnet-container \
    algorand/algod:latest

Note: Explicit volume creation is not needed. You are also able to mount a local directory to the container by replacing -v algod-data:/algod/data with -v path/to/localdirectory:/algod/data

Now, when you gracefully shut down your container by issuing:

docker stop mainnet-container

Your algod-data volume should persist, allowing you to spin up the container again with the data that you left off with.

“Ok, that was cool. But what if I want to interact with my Algod node through the REST API”?

Let’s take our example a bit further. To enable the REST API, you will include two extra variables when you spin up your container:

docker run --rm -d \
    -e NETWORK=mainnet \
    -e FAST_CATCHUP=1 \
    -e TOKEN="YOUR_API_TOKEN" \ #must be >=64 char
    -p 4190:8080 \
    -v algod-data:/algod/data \
    --name mainnet-container \
    algorand/algod:latest

By assigning the REST API key through the TOKEN environmental variable, and by mapping the internal Algod REST API to local port 4190 (through -p 4190:8080), your Algod node will be able to accept incoming REST API connections on localhost:4190.

If life takes you by storm and you forget what you set as your API token, you can always recover it by issuing:

docker exec -it mainnet-container cat /algod/data/algod.token

This will then return the REST API key assigned to the Algod process running in your container.

Note: Spinning up a new container with the TOKEN environmental variable specified and a previous mounted volume, the Algod token will be overwritten. This could be a benefit if a new REST API key is desired.

To summarize, the example provides a fully functional non-participating Algod node that is:

Running in a containerized environment
Connected to the Algorand mainnet network
Immediately started with fast catchup
REST API ready
Capable of being spun up and down with persistent blockchain data

Please refer to the Algorand/Algod DockerHub documentation for information on other potential uses of the container such as:

Launching the container in a private network with Dev Mode enabled
Launching the container with our Key Management Daemon (KMD) enabled

Create Publication