playground


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