A lot of people are having problems setting-up a dev environment with Plutus PAB and Plutus Playground. In this article, I am going to summarize the method I use to install everything and get it working on an Ubuntu virtual machine with 8Mb of available RAM.
WARNING: this article will age relatively quickly and is only verified for the time of writing (January, 2022). This represents the current canonical build for installing a working instance of Plutus PAB and Plutus Playground. There are a number of reasons that people are having so many problems:
- Using out-of-date instructions
There are still a bunch of instructions from previous cohorts of the Plutus Pioneer Program (PPP) that are no longer applicable. The instructions in this article are only good for the 3rd Cohort (Jan-Mar, 2022) of the PPP. Things can and probably WILL change. - Using the wrong git repository
There are some different git repositories around (plutus, plutus-core, etc.) but the current repo that you should be using at this point is the plutus-apps repo: https://github.com/input-output-hk/plutus-apps. Accept no substitutes! - Missing important setup steps
In particular, the Nix build and package management system is quite complex and there are a few pitfalls to watch out for. The more you read about and understand how Nix works, the fewer problems you should experience.
I : Install the toolchain: Git & Nix
You will need to have git installed on your system to checkout the code from the repository. On most Linux systems, git will already be preinstalled. If not, you can install using your Linux package manager. On Ubuntu, that would be a command on the terminal something like:
# update your package list
sudo apt update
# install git curl
sudo apt install git curl
# clone the plutus repo
git clone https://github.com/input-output-hk/plutus-apps
Next you will need to install and configure Nix as a multiuser installation (recommended):
sh <(curl -L https://nixos.org/nix/install) --daemon
WHAT IF this gives me an error?
NOTE: This command can fail (it does on my Ubuntu install) and IF that happens you can use the fail-safe method to run the script for a multiuser installation (recommended):
# download the install script
curl -L https://nixos.org/nix/install > nix-install.sh
# make it an executable script
chmod 755 ./nix-install.sh
# run the script
./nix-install.sh --daemon
DO: run these commands as a regular system user.
DONT: run them as root
or with sudo
— Nix will invoke sudo when it needs to.
WHAT will it do?
- Create a system group called
nixbld
- Create 32 user accounts (
nixbld1 - nixbld32
) and assign them to thenixbld
group - Backup your
/etc/bash.bashrc
file to/etc/bash.bashrc.backup-before-nix
- Add a new /
etc/bash.bashrc
file with references to /etc/profile.d/nix.sh
- Setup and start the
nix-daemon --daemon
background process - Create a TCP/IP socket:
/nix/var/nix/daemon-socket/socket
WHAT IF I mess it all up and have to start again cleanly?
sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
# If you are on Linux with systemd, you will need to run:
sudo systemctl stop nix-daemon.socket
sudo systemctl stop nix-daemon.service
sudo systemctl disable nix-daemon.socket
sudo systemctl disable nix-daemon.service
sudo systemctl daemon-reload
# restore your /etc/bash.bashrc profile from backup
sudo mv /etc/bash.bashrc.backup-before-nix /etc/bash.bashrc
HOW DO I KNOW that the service and sockets are running properly?
If you are running a Linux distro that uses systemd (like Ubuntu), you can control your processes using the systemctl
command.
VIEW the status of your daemon service
sudo systemctl status nix-daemon.service
You should see OUTPUT like:
● nix-daemon.service - Nix Daemon Loaded: loaded (/etc/systemd/system/nix-daemon.service; linked; vendor preset: enabled) Active: active (running) since Tue 2022-01-11 23:46:52 UTC; 11h ago TriggeredBy: ● nix-daemon.socket Main PID: 1976632 (nix-daemon) Tasks: 5 (limit: 9458) Memory: 1.0G CPU: 8min 12.334s CGroup: /system.slice/nix-daemon.service └─1976632 nix-daemon --daemon Jan 12 00:35:21 localhost nix-daemon[1976632]: accepted connection from pid 2149020, user nyk Jan 12 00:35:22 localhost nix-daemon[1976632]: accepted connection from pid 2149020, user nyk
VIEW the status of your socket
sudo systemctl status nix-daemon.socket
You should see OUTPUT like:
● nix-daemon.socket - Nix Daemon Socket Loaded: loaded (/etc/systemd/system/nix-daemon.socket; enabled; vendor preset: enabled) Active: active (running) since Tue 2022-01-11 23:43:00 UTC; 11h ago Triggers: ● nix-daemon.service Listen: /nix/var/nix/daemon-socket/socket (Stream) CGroup: /system.slice/nix-daemon.socket Jan 11 23:43:00 localhost systemd[1]: Listening on Nix Daemon Socket.
II – Build the project
First, you must configure Nix to use the IOHK nix cache, otherwise the build will take many hours as without the cache it will compile the GHC libraries from source. You can do this in either /etc/nix/nix.conf or in ~/.config/nix/nix.con
f. Add these two lines (two key/values) to the nix.conf file:
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=
Now go to the plutus-apps root directory and start the build by entering the Nix shell:
cd ~/plutus-apps
nix-shell
It will start to output trace messages to your terminal as it builds the dependencies for the project. If the messages say that it is compiling GHC and you see no messages about copying files from hydra.iohk.io, iohk.cachix.org, and cache.nixos.org, then exit the shell (ctl-c
). Check your nix.conf file to make sure everything is correctly setup and maybe try to restart the nix-daemon process. Then try again.
III – Start the Plutus Playground Server & Client
From within the nix shell, you will move to the plutus-playground-client directory to start the server:
nix-shell #if you had left the nix shell
cd ./plutus-playground-client
plutus-playground-server
The service will start, running in the foreground, which means that if you close the terminal, the service process will also terminate (i.e. it does not run as a daemon process in the background). To build and start the client service (built with Purescript), you must start another terminal with another nix-shell:
cd ~/plutus-apps
nix-shell
cd ./plutus-playground-client
npm start
Once the compilation of purescript has completed and the webpack has run, you should be able to open up the web interface in your browser at https://localhost:8009/. That’s it!