Cheatsheet Ubuntu 20.04 VM

/!\ This setup is only compatible with Substra v.0.6.0. It will soon be updated. Please refer to the compatibility table for further information.

/!\ This configuration is totally not suitable for production environment!


Hardware check

Please check first the hardware-related information of your machine and update accordingly installation procedures. This guide aims at x86_64 machines.

uname -mp

System updates

sudo apt update && \
    sudo apt upgrade -y && \
	sudo apt autoremove --purge -y && \
	sudo apt autoclean

Softwares installation


sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common \
    socat # needed by k8s/skaffold in virtualized context

curl -fsSL | sudo apt-key add -

sudo add-apt-repository \
    "deb [arch=amd64] \
    $(lsb_release -cs) \

sudo apt-get update && \
    sudo apt-get install docker-ce docker-ce-cli

sudo groupadd docker
sudo usermod -aG docker $USER

Minikube v1.9.2

curl -LO && \
    sudo install minikube-linux-amd64 /usr/local/bin/minikube && \
    rm -rf minikube-linux-amd64

Kubectl v1.16.7

curl -s | sudo apt-key add - && \
    echo "deb kubernetes-xenial main" | sudo tee -a /etc/apt/sources.list.d/kubernetes.list

sudo apt-get update && \
    sudo apt-get install -y kubectl=1.16.7-00 -V

Helm v2.16.1

curl -LO && \
    tar xzvf helm-v2.16.1-linux-amd64.tar.gz && \
    sudo mv linux-amd64/tiller linux-amd64/helm /usr/local/bin/ && \
    rm -rf helm-v2.16.1-linux-amd64.tar.gz linux-amd64

Skaffold v1.8.0

curl -Lo skaffold && \
    chmod +x skaffold && \
    sudo mv skaffold /usr/local/bin

k9s v0.22.0

Note: this one is not mandatory but it is such a great k8s tool that I couldn’t resist to add it!

mkdir k9s && cd k9s && \
    curl -L0 && \
    tar xzvf k9s_Linux_x86_64.tar.gz && \
    sudo mv k9s /usr/local/bin && \
    rm -rf k9s


Minikube config

sudo minikube start --vm-driver=none --kubernetes-version='v1.16.7'

In case of HOST_JUJU_LOCK_PERMISSION error, please update as follow:

sudo sysctl fs.protected_regular=0

Enable addons

# Check minikube status
sudo minikube status

# Check the enabled addons
sudo minikube addons list

# You'll need at least ingress & helm-tiller addons activated
sudo minikube addons enable ingress && \
    sudo minikube addons enable ingress-dns && \
    sudo minikube addons enable helm-tiller

Helm init

sudo helm init && \
    sudo kubectl get pods --namespace kube-system | grep tiller

Add bitnami repo to Helm repos

sudo helm repo add bitnami

Network quick config

On the server

echo "$(sudo minikube ip)" | sudo tee -a /etc/hosts

On your local machine (Mac & Linux)

Set the server external ip in the /etc/hosts file.

Please replace <SERVER-EXTERNAL-IP> with the external ip of your server.

echo "<SERVER-EXTERNAL-IP>" | sudo tee -a /etc/hosts

Clone the repositories and switch to the correct version

Please refer to the compatibility table.

Note: this is a setup compatible with substra v0.6.0

mkdir substra && cd substra
git clone --branch 0.6.0
git clone --branch 0.0.12 # or checkout fe33fc0 ¯\_(ツ)_/¯
git clone --branch 0.0.17
git clone --branch 0.0.19

Fire up

Note: In hlf-k8s repository, you will need to update the skaffold.yaml file and edit the chaincodes[0].src variable for each organisation. You will have to use the correct chaincode version according to the compatibility table, for example, with substra v0.6.0: chaincodes[0].src:

# start hlf-k8s
cd hlf-k8s && sudo skaffold run

# start the backend
cd ../substra-backend && sudo skaffold run

# start the frontend
cd ../substra-frontend && sudo skaffold run

# Quick test on backend node-1
# From the server & from your local machine:
# should return "OK"

If you didn’t see OK:

  • Check that your /etc/hosts file is using the correct ip and that domains are registered

  • Use k9s

  • Check the troubleshooting section

  • We also have a #help channel on Slack