How to run an dockerized Alephium full node

Supply-chain attacks are quite popular these days, as the Solarwind hack highlighted. Don’t trust blindly containers, and run sanity checks on your environment(s)!

Alephium is a sharded blockchain which, at the time of writing, plan to launch its mainnet in September 2021 🤞. Details about Alephium is out of the scope of this article, but I strongly recommend to get to know this awesome project.

Running a full node in 10 seconds

Alephium Wiki provides some guidance on how to run a full node in the testnet. I will show here how to run a full node in Docker, based on the freshly merged contribution here.


Docker is the main pre-requisite here. Please check the official getting started to install Docker in your environment.

Provided image

Once Docker is running, a ready-to-be-run image is available in Docker Hub:

Images are build using, and are available for amd64(x86_64), arm64 and arm/7 platforms. Arm64 version make Alephium nodes running on a Raspberry Pi 4. Read How to install a Raspberrry Pi 4 if you’re interested in a automated installation process.

docker pull alephium/alephium:v0.9.0


The container already contains a minimal config file to connect to the testnet. No need of further configuration by now.

Run your container

Just run it!

From a command line (terminal, shell, PowerShell, …), just type the following command:

docker run -it --rm -p 12973:12973 --name alephium alephium/alephium:v0.9.0
This configuration do NOT persist the blockchain database nor the wallet(s). Restarting the container will make you LOOSE everything!

Congratulations 🎉! You now have a Alephium full node running (synching) 🚀. You can interact with it through its API:

Advanced configuration

This second section will go a bit beyond the “hello Alephium” example describe in the first section.

Data (chain & wallet) persistence

As mentioned above, the basic example do not persist neither the wallet(s) nor the blockchain. Restarting the container implies to re-sync (and hence download) the chain. The docker compose section below helps you persisting the chain and the wallets.

Docker compose

While running using plain docker works, it’s not my favourite approach. A docker-compose file is available in Alephium source code:

Please make sure docker-compose is installed before going further. And as always, please refer to the official documentation if you’re stuck with the install.

Assuming you have downloaded both the docker-compose and the minimal config file to connect to the testnet, you can:

  1. create two folders alephium-data and alephium-wallets (mkdir alephium-data alephium-wallets in a shell),
  2. gives them write-all permissions (chmod 777 alephium-data alephium-wallets in a shell),
  3. uncomment the two last lines in docke-compose.yml file (the ones talking about alephium-data and alephium-wallets)
  4. and you’re ready to go! Launch the container using docker-compose command (docker-compose up -d in a shell)

If you’re intested in digging further, please open it and read the docker-compose.yml file, it contains quite some crunch details.