Complete Walkthough Installing Canton Community v 0.27.0 Ubuntu Server

This tutorial is based on a clean install of Ubuntu Server (20.04.3 LTS) GNU/Linux, and will assist in the installation of Canton Community version 0.27.0.

Operating System (OS): Ubuntu Server (20.04.3 LTS)
Kernel: Linux version 5.4.0-84-generic
Canton: Community version 0.27.0

This tutorial assumes very little GNU/Linux Command Line Interface (CLI) knowledge, other than that you can open a Terminal, and follow instructions. If you are proficient, feel free to skim through this tutorial as needs be.

This tutorial will require these packages:

Wget: GNU Wget is a command-line utility for downloading files from the web
Tree: A command line utility that displays file structures in a directory
Java: A programming language and computing platform now supported by the Oracle Corporation
Canton: Is a Daml ledger interoperability protocol
PostgreSQL: A powerful, open source RM Database application
  1. The use of # is similar to a comment in a program, for information only.
  2. The use of $ indicates the terminal prompt from the system user perspective, and is this case, the $user is ‘quid’. If the #ROOT user is to be used, the terminal prompt will be displayed like this:
    root@host:/home/quid#
  3. This tutorial is aimed at the absolute novice, and has simple commands that are very sequential, even repetitive.
  4. If any of the following packages already exist on your system, execute the commands anyway, it will cause no issue, other than warnings.
  5. Every word or abbreviation after the $ is a command to be executed. Type the short commands in directly but use Copy & Paste for others.
  6. This tutorial commences in a Terminal in the /home/your_user directory.

Canton compatibility:

Dependency	Version
-----------------------------------------------------------------------------------
Java Runtime	OpenJDK 64-Bit Server VM 18.9 (build 11.0.12+7, mixed mode, sharing)
Daml SDK        1.16.0
Postgres        postgres (PostgreSQL) 11.11 (Debian 11.11-1.pgdg90+1)
CCF             0.14.2
Ethereum        besu/v20.10.4/linux-x86_64/oracle_openjdk-java-11
Fabric          2.2.2

Tree

# Install the `tree` command
$ sudo apt update && sudo apt upgrade
$ sudo install tree

Java

# Verify if Java is installed, Canton requires Java > 11.0
$ java --version

Command 'java' not found, but can be installed with:

sudo apt install openjdk-11-jre-headless  # version 11.0.11+9-0ubuntu2~20.04, or
sudo apt install default-jre              # version 2:1.11-72
sudo apt install openjdk-13-jre-headless  # version 13.0.7+5-0ubuntu1~20.04
sudo apt install openjdk-16-jre-headless  # version 16.0.1+9-1~20.04
sudo apt install openjdk-8-jre-headless   # version 8u292-b10-0ubuntu1~20.04

Install OpenJDK v11 Headless

$ sudo apt install --dry-run openjdk-11-jre-headless
$ sudo apt install -y openjdk-11-jre-headless
---
---
Setting up openjdk-11-jre-headless:amd64 (11.0.11+9-0ubuntu2~20.04) ...
---
---

# Confirm correct version is installed
$ java --version
openjdk 11.0.11 2021-04-20
OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04)
OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode, sharing)

Confirm installed JAVA Library

$ cd /usr/lib/jvm
$ ls | grep java
java-1.11.0-openjdk-amd64
java-11-openjdk-amd64

Set the JAVA_HOME environment

$ nano ~/.bashrc

# Add to bottom of file
export JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64

# Source ~/.bashrc or Logout/Login
$ source ~/.bashrc

# Verify the ENV is set correctly
$ echo $JAVA_HOME
/usr/lib/jvm/java-1.11.0-openjdk-amd64

Canton Community version 0.27.0

# Change to download directory
$ cd ~/Downloads

# Source latest Canton-Community archive (0.27.0)
$ wget https://github.com/digital-asset/canton/releases/download/v0.27.0/canton-community-0.27.0.tar.gz

# Create new directory for the Canton install
$ mkdir -p ~/opt/

# Copy the Canton archive into the newly created `opt` directory
$ cp -v ~/Downloads/canton-community-0.27.0.tar.gz ~/opt/

# Change to the `opt` directory & extract the archive
$ cd ../opt
$ tar zxvf canton-community-0.27.0.tar.gz

# Change into Canton directory
$ cd canton-community-0.27.0/

# Set the environment variable “CANTON” to where
# you have unpacked the Canton release bundle.
$ export CANTON=`pwd`

# Set variable that points to the advanced example directory
export CONF="$CANTON/examples/03-advanced-configuration"

PostgreSQL on Ubuntu

# Edit sources.list/d to pin PostgreSQL repository
$ sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# Import the repository signing key
$ wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
OK

# Update & upgrade system
$ sudo apt update -y && sudo apt upgrade -y

# Install the latest version of PostgreSQL
$ sudo apt install --dry-run  postgresql postgresql-client 
$ sudo apt install -y postgresql postgresql-client

Start PostgreSQL & create Database

# Start PostgreSQL Server Cluster
$ sudo pg_ctlcluster 13 main start

# Access PostgreSQL
$ sudo -u postgres psql

# Create new Database for Canton
postgres=# create database daml_canton;

# Create new User & Password
# Substitute User `quid` for `your_user`
postgres=# create user quid with encrypted password 'cantoncanton';

# Grant new User all privileges on Database daml_canton [X]
# Substitute User `quid` for `your_user`
postgres=# grant all privileges on database daml_canton to quid;

# Exit the PostgreSQL admin interface [X]
postgres=# exit

# Verify the PostgreSQL version [X]
$ psql --version
psql (PostgreSQL) 13.4 (Ubuntu 13.4-1.pgdg20.04+1)

View Canton Community file structure

# Return to the Canton installation directory
$ cd opt/canton-community-0.27.0/

# Confirm the installed archive structure
# directories only, using the Tree or Find commands
$ tree -d -L 2 .
.
|-- bin
|-- daml
|   `-- CantonExamples
|-- dars
|-- demo
|   |-- config
|   |-- daml
|   |-- dars
|   |-- images
|   `-- lib
|-- deployment
|   |-- aws
|   |-- azure
|   `-- docker
|-- examples
|   |-- 01-simple-topology
|   |-- 02-global-domain
|   |-- 03-advanced-configuration
|   |-- 04-create-daml-app
|   |-- 05-composability
|   |-- 06-messaging
|   |-- 07-repair
|   `-- scripts
`-- lib

24 directories

Start Canton

# Make a simple Canton_Repl_Help.txt file to refer to:
$ touch canton_repl_help.txt
$ bin/canton --help > canton_repl_help.txt

# Start an instance of Canton, using the REPL only
$ bin/canton --help

# Start an instance of the First Example
$ bin/canton -c examples/01-simple-topology/simple-topology.conf
Compiling (synthetic)/ammonite/predef/ArgsPredef.sc
Compiling /home/dietpi/Downloads/canton-community-0.26.0/(console)
   _____            _
  / ____|          | |
 | |     __ _ _ __ | |_ ___  _ __
 | |    / _` | '_ \| __/ _ \| '_ \
 | |___| (_| | | | | || (_) | | | |
  \_____\__,_|_| |_|\__\___/|_| |_|

  Welcome to Canton!
  Type `help` to get started. `exit` to leave.

# If you can see the above ASCII 'Canton', the app is working as per spec

# Review the available help within the Canton REPL
@ help 
Top-level Commands
------------------
exit - Leave the console
help - Help with console commands; type help("<command>") for detailed help for <command>

Generic Node References
-----------------------
domains - All domain nodes
nodes - All nodes
participants - All participant nodes

Node References
---------------
mydomain - Manage local domain 'mydomain'; type 'mydomain help' or 'mydomain help("<methodName>")' for more help
participant1 - Manage participant 'participant1'; type 'participant1 help' or 'participant1 help("<methodName>")' for more help
participant2 - Manage participant 'participant2'; type 'participant2 help' or 'participant2 help("<methodName>")' for more help

Command Groups
--------------
console - Configure behaviour of console
health - Environment health inspection
logging - Logging related commands
utils - Console utilities

# Leave the console
@ exit
Bye!

You should have a working Canton Community version 0.27.0 on your Ubuntu Server system. If not, review any error messages, refer back to the relevant section and try again. Failing that, reply to this thread and we can help you.

6 Likes