pioneers


Plutus Playground Minimal Ubuntu Setup

This document is written for the third iteration of Cardano’s Plutus Pioneers Program. It demonstrates the steps required to install and execute the Plutus Playground Server.

All credit belongs to Deceptikon, who can be reached on Discord: @Deceptikon#9964. I am simply relaying his excellent work here.

Install nix:

1
sh <(curl -L https://nixos.org/nix/install) --no-daemon

Close your active terminal and reopen it. Doing this provides a fresh terminal session with nix enabled (p.s., I am brand new to nix).

nix requires some configuration:

1
2
3
cd ~/.config
mkdir nix
cd nix

Create a new nix.conf file. I use vim for most things. You can use whatever you like.

1
vim nix.conf

Paste the following lines into the nix.conf:

1
2
3
substituters = https://hydra.iohk.io https://iohk.cachix.org https://cache.nixos.org/
trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
experimental-features = nix-command

Save and close the document.

Test to see if nix is installed:

1
nix-env --version

You should see something like this:

1
nix-env (Nix) 2.5.1

Now it’s time to download and build the Plutus Playground. It’s up to you where you store the software, just so long as you are mindful of its location. For demonstration purposes, the relevant plutus-app software will be located in your home directory:

1
2
3
cd
git clone https://github.com/input-output-hk/plutus-apps
cd plutus-apps

At the time of writing, you need to checkout the correct revision of the repository you just downloaded. You can determine the revision number by consulting the plutus-pioneer-program repository.

Using the code for Week 1 as an example, look for the code/week01/cabal.project file. You will find the required revision number under the source-repository-package > tag configuration. I suspect you will need to look for this revision in each week’s code.

1
git checkout 41149926c108c71831cfe8d244c83b0ee4bf5c8a

Finally, build the client and server software.

1
nix-build -A plutus-playground.server

This may take some time. Deceptikon has some good advice:

If this step takes longer than 10 minutes, abort! If the build takes longer than that, the IOHK binary caches are not configured correctly. Most likely your nix.conf is not in the correct folder. It should be right if you EXACTLY followed the steps and are using a fresh install of Ubuntu. Others such as MacOS may require nix.conf to be in a different folder or may require multi-user install of nix. If you think to yourself, as I did, “I’ll just let it run overnight!” the only result will be a huge waste of time on something that doesn’t work

I’m not sure if the following is totally necessary, but Deceptikon recommends you close the working terminal window. Open it again and execute:

1
. /home/yourusernamehere/.nix-profile/etc/profile.d/nix.sh

Be sure to change the yourusernamehere part of the path to your actual username.

Go to your plutus-apps directory (if you’re not there already) and launch the nix shell:

1
2
cd ~/plutus-apps
nix-shell

This will probably take a bit of time on first execution.

Once nix-shell is all warmed up:

1
2
cd plutus-playground-server/
plutus-playground-server

This is what I saw on my first successful execution:

1
2
3
4
5
6
7
8
plutus-playground-server: for development use only
[Info] Running: (Nothing,Webserver {_port = 8080, _maxInterpretationTime = 80s})
Initializing Context
Initializing Context
Warning: GITHUB_CLIENT_ID not set
Warning: GITHUB_CLIENT_SECRET not set
Warning: JWT_SIGNATURE not set
Interpreter ready

Look for the Interpreter ready. That’s the important part!

At this point you have a server running. Open a second terminal window and ensure you are in the plutus-apps directory. You need to start nix-shell again:

1
2
3
4
cd ~/plutus-apps
nix-shell
cd plutus-playground-client
npm run start

As before, if this the first time executing the program, it may take a while to get going.

Once ready, you can open the Playground interface in your favourite browser at https://localhost:8009/. You may get a scary Invalid Certificate error, but you can safely ignore that.

Now try compiling some of the sample code: Lecture #1 - Part #5 - Auction Contract on the Playground

All good?

Optional: For convenience, build and serve the Plutus documentation locally:

1
2
3
cd ~/workspace/plutus-apps
nix-shell
build-and-serve-docs

View at http://localhost:8002/haddock


Plutus Pioneers - Weekly Environment Setup with git and nix-shell

Week 2 Lecture 2 is upon us, Plutus Pioneers! In order to follow along, you’ll need to update your work environment. You’ll likely need to follow these steps for each subsequent week.

Checkout this Week’s Revision

Last week you cloned and built the plutus-apps repository on your computer. Consider the plutus-apps directory your launch point for coursework. It was within this context that you built and executed the Plutus Playground Server and its client.

This first step is a little hairy. Hang on tight…

Judging by the steps taken in Week 1, you’ll likely need to rebuild the Playground client and server every new week. To do this, you must checkout the correct revision of the plutus-apps repository. You can determine the revision number by consulting the plutus-pioneer-program repository.

Using the code for Week 2 as an example, look for the code/week02/cabal.project file. You will find the required revision number under the source-repository-package > tag configuration. Week 2’s revision number looks like this: 6aff97d596ac9d59460aab5c65627b1c8c0a1528.

Get ready to copy/paste that number. But first, navigate to the plutus-apps directory. For me, this step looks like this:

1
cd ~/workspace/plutus-apps

Update the repository in case there were any recent changes:

1
2
git checkout main
git pull

Now, checkout the correct revision:

1
git checkout 6aff97d596ac9d59460aab5c65627b1c8c0a1528

Phew! I don’t know for sure, but I suspect you’ll need to do this every week.

Rebuild and Execute the Plutus Playground

This assumes that you were successful in setting up nix.

Continuing from above, execute:

1
nix-build -A plutus-playground.server

Start nix-shell:

1
nix-shell

Start the Plutus Playground Server:

1
2
cd plutus-playground-server/
plutus-playground-server

The server should now be executing in the foreground of your terminal. Leave this open. Open a second terminal window and start the client (steps consolidated here):

1
2
3
4
cd ~/workspace/plutus-apps/
nix-shell
cd plutus-playground-client
npm run start

Now the client is running. You can see it at https://localhost:8009 in your favourite browser. Leave this terminal open as well.

Update the Course Code and Get to Work

Open a new terminal window and start nix-shell:

1
2
cd ~/workspace/plutus-apps/
nix-shell

By now, it should be clear that the plutus-apps directory contains what you need to get the provided environment up and running. Now, navigate to your plutus-pioneers-program directory:

1
cd ../plutus-pioneers-program

Update the local repository:

1
git pull

You now have this week’s lesson material. Navigate to the directory and build the project:

1
2
cd code/week02/
cabal build

Time for me to start watching the new lectures


Minimal Haskell Dev Setup on Ubuntu

This documents the steps required to prepare a development environment for Haskell in Ubuntu. All of this is straight-up jacked from here. I’m brand new to the Haskell ecosystem. I am learning the language so that I can build and test Plutus smart contracts on Cardano.

Note to Plutus Pioneers: the following instructions are not executed from within the context of nix (i.e., I’m not running nix when I’m running these commands…)

Basic tool setup

First, install some system dependencies:

1
sudo apt install build-essential curl libffi-dev libffi6 libgmp-dev libgmp10 libncurses-dev libncurses5 libtinfo5

Then, install GHCup:

1
curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh

You will be prompted to make some decisions. I generally like to stick with defaults, and that’s mostly true here. However,

  1. I answered Y to installing the haskell-language-server. This is so I can leverage language features in my favourite editor, vim.
  2. I answered Y to installing stack. Here’s some context.

At the end of it, you should have GHC, cabal-install, stack, and haskell-language-server.

In all the steps taken so far I’m not sure what went wrong, but stack never actually arrived. Thankfully, the Haskell docs provide a backup:

1
curl -sSL https://get.haskellstack.org/ | sh

Optional: Configure the Language Server for Vim

vim is the only editor I use. If you have the haskell-language-server installed, you can do something similar with your favourite tool.

I tried to take the path of least resistance by using the Coc configuration/installation instructions. Again, I’ve purposefully avoided executing within the provided Plutus nix-shell environment. The instructions are distilled as follows…

Install vim-plug:

1
2
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim

Configure vim-plug:

1
vim ~/.vimrc

Paste this somewhere toward the top of the file where you won’t be busting up any logical blocks:

1
2
3
4
5
6
7
"""
" vim-plug extensions
call plug#begin('~/.vim/plugged')

Plug 'neoclide/coc.nvim', {'branch': 'release'}

call plug#end()

Run this command in vim:

1
:PlugInstall

This will download whatever plugins are included before the plug#begin and plug#end.

Again, issue this command in vim:

1
:CocConfig

Paste this into the Coc config file:

1
2
3
4
5
6
7
8
9
10
{
"languageserver": {
"haskell": {
"command": "haskell-language-server-wrapper",
"args": ["--lsp"],
"rootPatterns": ["*.cabal", "stack.yaml", "cabal.project", "package.yaml", "hie.yaml"],
"filetypes": ["haskell", "lhaskell"]
}
}
}

Bootstrap a project with Stack

I spend most of my time in a node environment. If you’re familiar with the Javascript ecosystem, stack appears analagous to npm.

To start a new project with the default template, navigate to your preferred project directory and initialize:

1
2
3
cd ~/workspace
stack new my-project
cd my-project

You now have a directory containing almost everything you need to start work. Facilities for testing are sketched in but aren’t actually configured when bootstrapping from the default template.

Just for fun, try:

1
stack test

You can also build the minimal project:

1
stack build

And execute:

1
stack exec my-project-exe

To launch the REPL:

1
stack ghci

Haskell and all it’s goodies, ready to go.

Next up… I’m figuring out testing tools.