Plutus Playground Setup on Windows (outdated)

Notes

This guide will show you how to set up a Plutus Playground in Debian running on WSL2 in Windows. It also contains specific instructions which are usefull for Plutus Pioneers. However it can be used by anyone who wants to run the Plutus Playground on Windows.

This guide will not require you to use an editor outside of debian or even docker. However, as these are popular options I have included optional sections for installation of VSCode editor, WIndows Terminal and Docker.

You can follow this guide for any Linux distribution. This guide will use Debian, and it is the one I recommend if you don't have a specific preference. If you choose another distribution, you will need to substitute some of the Debian Bash commands with the equivalent in your chosen distribution.

Legend

Please pay close attention to which directory each command is called from in the code boxes. Each line will start withh clearly denoting both directory and context before each command. This guide will assume you know how to change directories in Debian and for conciseness has omitted changing of directory and between shells. Make sure you cd into the proper directory in the proper shell by referring to this legend.

Home directory in Debian 

~$

Home directory inside of nix-shell in Debian

[nix-shell ~$]

Command prompt in Windows (Elevated)

C:\>

1. Install WSL2

Follow the steps here to install WSL2 on Windows

https://docs.microsoft.com/en-us/windows/wsl/install-win10

In step 6 you will be asked to install a distribution of linux on your new WSL2. Choose Debian or any other distribution. This guide will be specific to Debian.

When Windows installs your Debian, you will choose a user name and password. You will need these, so choose something fitting.

2. Prepare your linux

You will need some programs installed in Debian to be able to complete this guide. Technically you don't absolutely need VIM if you really dont want it, but I would suggest installing it all the same.

~$ sudo apt-get update
~$ sudo apt-get upgrade

~$ sudo apt-get install wget vim git curl npm

3. Install Nix

~$ sudo curl -L https://nixos.org/nix/install | sh

The following will edit the nix configuration to aid you in building plutus from nix. 

~$ sudo mkdir /etc/nix
~$ sudo touch /etc/nix/nix.conf
~$ sudo chmod 777 /etc/nix/nix.conf
~$ echo "sandbox = false
use-sqlite-wal = false
system-features = kvm
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=" >> /etc/nix/nix.conf
~$ sudo chmod 644 /etc/nix/nix.conf
~$ bash

4. Get Plutus and Plutus Playground repositories

These are tho only depositories needed for running Plutus Playground. You do not need the plutus-starter repository.

~$ mkdir code

~/code$ git clone https://github.com/input-output-hk/plutus
~/code$ git clone https://github.com/input-output-hk/plutus-pioneer-program

5. Build Plutus

If you are not a putus pioneer, then skip the next code box (nix build -f default.nix ...).

If you are a plutus pioneer, then first checkout the correct commit. You can read more about why this is necessary in the optinal section for pioneers.

~/code/plutus$ cat ~/code/plutus-pioneer-program/code/weekxx/cabal.project | grep -m 1 tag:
~/code$ git checkout ${commit-hash-tag-from-above-output}

Now build Plutus 

~/code/plutus$ nix build -f default.nix plutus.haskell.packages.plutus-core.components.library

6. Build Plutus Playground

~/code/plutus$ nix-build -A plutus-playground.client
~/code/plutus$ nix-build -A plutus-playground.server

7. Build dependencies

~/code/plutus$ nix-build -A plutus-pab
~/code/plutus$ nix-build -A plutus-playground.generate-purescript
~/code/plutus$ nix-build -A plutus-playground.start-backend

8. Start Plutus Playground server

You are finally ready to fire up Plutus Playground.

~/code/plutus$ nix-shell

[nix-shell ~/code/plutus/plutus-pab$] plutus-pab-generate-purs
[nix-shell ~/code/plutus/plutus-playground-server$] plutus-playground-generate-purs
[nix-shell ~/code/plutus/plutus-playground-client$] plutus-playground-server -i 120s

9. Start the Plutus Playground client

~/code/plutus$ nix-shell

[nix-shell ~/code/plutus/plutus-playground-client$] npm run start

At this point you have everything you need to run plutus playground and the npm will tell you towards the end of its output where you can access it. Default is https://localhost:8009/, so open up your broser and head on over.

In the playground you can use the in browser editor to write code, compile and simulate scenarios. There are also very usefull links in the top right if you need some help getting started. I recommend using these guides for any further information on the specifics of the actual playground.

Switching week (Plutus Pioneers Only)

In the plutus pioneer program, each week you will have to adjust so you are using the correct commit of plutus. You need to match the correct Plutus repository commit hash for the weeks excercises.

Stop the client, server and repl if they are running.

Then update Plutus and Plutus Pioneer Program repositories.

~/code/plutus$ git pull origin master
~/code/plutus-pioneer-program$ git pull origin master

Find this weeks correkt plutus commit tag hash.

~/code/plutus-pioneer-program/code/weekxx$ cat cabal.project | grep -m 1 tag:
~/code/plutus$ git checkout ${commit-hash-tag-you-found-in-the-step-above}

Rebuild Plutus

~/code/plutus$ nix build -f default.nix plutus.haskell.packages.plutus-core

Start the server, client and repl again.

Starting the repl (Optional)

With cabal repl you can run GHCi (a sort of cli into the haskell) directly in your terminal. It is very usefull for compiling your code if you are editing it in your Debian environment with vim or any other editor, such as a connected VSCode in Windows. It is also necessary to run the repl if you want to follow along in the plutus pioneer lessons.

In the examples below replace the final directory ( .. weekxx) with the correct week name if you are following the pioneer program or another directory with your code.

~/code/plutus$ nix-shell
[nix-shell ~/code/plutus-pioneer-program/code/weekxx$] cabal update
[nix-shell ~/code/plutus-pioneer-program/code/weekxx$] cabal build
[nix-shell ~/code/plutus-pioneer-program/code/weekxx$] cabal repl

Installing VSCode Editor (Optional)

If you prefer to run VSCode editor over native linux editors then you can use this guide to install VSCode and then connect it to your linux distribution.

Install VSCode

https://code.visualstudio.com/download

Install "Remote - Development" extension pack [ms-vscode-remote.vscode-remote-extensionpack]

Install "Docker" extension [ms-azuretools.vscode-docker]

Install "Haskell Syntax Highlighting" extension [justusadam.language-haskell]

~/code$ code .

This will open VSCode with the directory tree in your ~/code directory. Anything inside will be accessible throught the editor. Saving, creating files, deleting files should all work seamlessly between VSCode and Debian at this point.

Installing Windows Terminal (Optional)

If you arent familiar with Windows Terminal, it is a program which lets you run a tabbed interface for your CLI programs, such as WSL2 instances, Powershell, Azure and Command Prompt. It will also let you configure colors, fonts and set other conveniant settings.

Install Windows Terminal

https://docs.microsoft.com/en-us/windows/terminal/get-started

Inside of Windows Terminal, open up settings and add a new profile pointing to your debian executable (located in %programfiles%/WindowsApps/)

If your windows user doesnt have access to the %programfiles%/WindowsApps/ folder, then you neeg to give yourself permission. In a command prompt with administrative privilages

C:\WINDOWS\system32> takeown /f "%programfiles%\WindowsApps"
C:\WINDOWS\system32> icacls "%programfiles%/WindowsApps" /grant %username%:RX

There are some additional things you could configure in Windows Terminal if you want to create a smooth environment. You could for example make a nix-shell profile that takes the debian executable and executes cd ~/code/plutus && nix-shell or even a Plutus server and Plutus client profle that simple fires up the server and client.

Installing Docker Desktop for Windows (Optional)

You do not need to use Docker if you follow this guide. However, as it is a popular option, I will mention how to do it here.

Follow the instructions located below to install Docker for Windows

https://docs.docker.com/docker-for-windows/install/

Launch Docker and make sure it has WSL2 enabled for your distribution (you will find this in Docker settings).

Before docker load, verify that docker works with.

~$ docker run hello-world

If you get an error, then try installing docker-load and also adding your user to the docker group

~$ sudo apt-get install docker-load

~$ sudo groupadd docker
~$ sudo usermod -aG docker ${user-name}

Now load the Plutus Docker

~/plutus$ docker load < $(nix-build default.nix -A devcontainer)

The docker will take some time to load. But if all goes well and you don't receive any more error messages, you are ready to go.