Running INSAcoin in Docker

I am currently taking part to a series of workshops organized by Crypto Lyon in partnership with INSA Lyon. The goal of those meetups is to teach how to use the blockchain technology by practising with an experimental coin : the INSAcoin. This is a coin forked from Litecoin and built during a lesson at INSA Lyon.

The first challenge for participants is to compile INSAcoin and run it on their own system, however, the build time can take up to one hour and the steps are different depending on your OS.

Docker allows us to perform the steps only one time and to distribute an image containing an up and running INSAcoin node. Furthermore, it allows us to use the same versioned environment and make our infrastructure reproducible.

So… Let’s create a Docker configuration together!

Installing Docker

If you don’t have Docker installed on your machine, you can refer to the official installation guide :

On Linux, you can simply run :

curl -sSL | sh

Next, let’s install docker-compose :

# Installation of docker-compose
sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# Setup autocompletion
sudo curl -L -o /etc/bash_completion.d/docker-compose

Configuring INSAcoin

First of all, let’s create a configuration file for INSAcoin on your host.

mkdir ~/.insacoin
touch ~/.insacoin/insacoin.conf

You can use the following configuration file (changing rpcuser/rpcpassword fields isn’t a bad idea).

More config examples :

Running the INSAcoin container

I already uploaded images on the dockerhub, so let’s just pull them to have INSAcoin up and running.

If you want to build those images yourself, you can refer to the following instructions and repo :

INSAcoin with GUI

To get started with the project, let’s play a little bit with the GUI.

In order to run the GUI from the container, we have to link the DISPLAY environment variable from our host and mount the X11 socket via a volume. We also mount the ~/.insacoin wallet to use our previously defined configuration and access the blocks.

xhost +local:docker && \
docker run -ti \
--name insacoin \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v ~/.insacoin:/root/.insacoin \
gnut3ll4/insacoin:0.10-ui \
insacoin-qt -txindex=1

This docker image is a bit heavy as we are using Qt, so, let’s explore instead INSAcoin in headless mode, so that we have a lighter image and use the cli to interact with it.

INSAcoin without GUI (headless)

If you don’t like to quit your terminal, this is the way to go!

We are still mounting the ~/.insacoin wallet directory in the container. There are different usable ports, whether we need a test environment or a regular node :

docker run -d --name insacoin \
-v ~/.insacoin:/root/.insacoin \
-p 7332:7332 \
-p 7333:7333 \
-p 17332:17332 \
-p 17333:17333 \
-p 19444:19444 \
gnut3ll4/insacoin:0.10-headless \
insacoind -txindex -rpcallowip=

The last parameter -rpcallowip is used to allow our host to access the container through RPC. As Docker ips are assigned dynamically, we specify a /16 range.

Try to interact with it, for exemple refreshing various state info with a watch :

watch docker exec -it insacoin insacoin-cli getinfo

However, for this solution to be really nice to use, we need something else : auto-completion!

Setup insacoin-cli auto-completion

This tip will allow us to use insacoin-cli through Docker, with auto-completion, as if it was actually installed.

  1. Install the INSAcoin bash-completion script :
sudo wget -N -P /etc/bash_completion.d/
source /etc/bash_completion.d/insacoind.bash-completion

2. Create a shortcut for insacoin-cli through Docker :

sudo cat > /usr/local/bin/insacoin-cli << EOF
docker exec -it insacoin insacoin-cli $@
insacoin-cli suggestions in action!

Setup the INSAcoin RPC explorer

Thanks to the modifications made by Antoine Poinsot to the initial btc-rpc-explorer project, we are now able to explore the INSAcoin blockchain, so let’s get everything in containers ;)

In the following docker-compose.yml, we have two containers : one for INSAcoin, the other for the rpc-explorer. Make sure your ~/.insacoin/insacoin.conf file contains rpcuser/rpcpassword fields, you can also set the IPSTACK_API_KEY field to geolocate peers in the explorer.

Then, you can run the following commands :

docker-compose pull
docker-compose up

Now let’s try the explorer by connecting to

Note : If you want the auto-completion previously set to work, you will need to update the /usr/local/bin/insacoin-cli script with the right container name instead of «insacoin» (something like «docker_insacoin-explorer_1» given by docker-compose)

A beautiful insacoin rpc explorer for us to use!

That’s it! But experiments aren’t over , so, if you want to improve things and contribute to INSAcoin, let’s meet on the repo!


Here are some references that I find very interesting and helpful :

  • This repo gives a lot of hints on how to use bitcoin with docker.
  • I learnt a lot about Docker thanks to this book, and there are a lot of practical examples
  • Have a look at Jessie Frazelle’s blog, there is a lot of Docker magic to learn in there!
  • … and of course, the INSAcoin repo ;)