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