algorand/algod repository overview

⁠Algod Container

General purpose algod container image.

⁠Image Configuration

Algorand maintains a Docker image with recent snapshot builds from our master branch on DockerHub to support users who prefer to run containerized processes. There are a couple of different images avaliable for running the latest stable or development versions of Algod.

• algorand/algod:latest is the latest stable release version of Algod (default)
• algorand/algod:stable is the latest stable version of Algod
• algorand/algod:{version}-stable is the stable version of Algod at a specific version number
• algorand/algod:beta is the version of Algod being considered for the next stable release
• algorand/algod:nightly is the latest development version of Algod

Algorand also publishes experimental versions of Algod.

• algorand/algod:{LONGSHA} is a version containing a specific commit to master
• algorand/algod:master is the version running on our master branch
• algorand/algod:feature-{branch} is the latest version of Algod on any of the go-algorand feature branches

Furthermore, There are a number of special files and environment variables used to control how a container is started. See below for more detail.

⁠Default Configuration

The following config.json overrides are applied:

⁠Environment Variables

The following environment variables can be supplied. Except when noted, it is possible to reconfigure deployments even after the data directory has been initialized.

⁠Special Files

Configuration can be modified by specifying certain files. These can be changed each time you start the container if the data directory is a mounted volume.

⁠Example Configuration

The following command launches a container configured with one of the public networks:

docker run --rm -it \
    -p 4190:8080 \
    -p 4191:7833 \
    -e NETWORK=mainnet \
    -e FAST_CATCHUP=1 \
    -e TELEMETRY_NAME=name \
    -e TOKEN=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \
    -e START_KMD=1 \
    -v ${PWD}/data:/algod/data/ \
    --name mainnet-container \
    algorand/algod:latest

Explanation of parts:

• -p 4190:8080 maps the internal algod REST API to local port 4190.
• -p 4191:7833 maps the internal kmd REST API to local port 4191.
• -e NETWORK=mainnet can be set to any of the supported public networks.
• -e TELEMETRY_NAME=name enables telemetry reporting to Algorand for network health analysis. The value of this variable takes precedence over the name attribute set in /etc/algorand/logging.config.
• -e FAST_CATCHUP=1 causes fast catchup to start shortly after launching the network.
• -e START_KMD=1 signals to entrypoint to start the kmd REST API (THIS SHOULD NOT BE USED IN PRODUCTION).
• -e TOKEN=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa sets the REST API token to use.
• -v ${PWD}/data:/algod/data/ mounts a local volume to the data directory, which can be used to restart and upgrade the deployment.

⁠Mounting the Data Directory

The data directory located at /algod/data. Mounting a volume at that location will allow you to shutdown and resume the node.

⁠Volume Permissions

The container executes in the context of the algorand user with UID=999 and GID=999 which is handled differently depending on your operating system or deployment platform. During startup the container temporarily runs as root in order to modify the permissions of /algod/data. It then changes to the algorand user. This can sometimes cause problems, for example if your deployment platform doesn't allow containers to run as the root user.

⁠Named Volume

Using a named volume will work without any specific configuration in most cases:

docker volume create algod-data
docker run -it --rm -d -v algod-data:/algod/data algorand/algod

⁠Use specific UID and GID

On the host system, ensure the directory being mounted uses UID=999 and GID=999. If the directory already has these permissions you may override the default user with -u 999:999.

⁠Private Network

Private networks work a little bit differently. They are configured with, potentially, several data directories. The default topology supplied with this container is installed to /algod/, and has a single node named data. This means the private network has a data directory at /algod/data, matching the production configuration.

Because the root directory contains some metadata, if persistence of the private network is required, you should mount the volume /algod/ instead of /algod/data. This will ensure the extra metadata is included when changing images.