Skip to main content
1

Install Node.js 22+

We recommend nvm to manage Node versions.
nvm install 22
nvm use 22
2

Install Yarn

Pastures uses Yarn Classic (1.x).
npm install -g yarn
3

Clone the repository

git clone https://github.com/IQCG/pastures-rancher.git
cd pastures-rancher
4

Install dependencies

yarn install --ignore-engines
The --ignore-engines flag is required because @rancher/shell may declare strict Node engine constraints that conflict with newer Node versions. The extension works correctly on Node 22+.
5

Build the extension

yarn build-pkg pastures
This compiles the extension into dist-pkg/.
6

Start the package server

yarn serve-pkgs
The dev server starts at http://127.0.0.1:4500 and serves the built extension artifacts. If you rebuild the extension, the server picks up the new files automatically.
7

Start or connect to Rancher

Option A — Docker (quick start):
docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:latest
Option B — Existing instance: Point your browser at your Rancher dashboard URL.
8

Developer Load the extension

  1. Open the Rancher UI and navigate to Extensions.
  2. Click the ⋮ menu (top-right) and select Developer Load.
  3. Enter http://127.0.0.1:4500 as the extension URL.
  4. The Pastures extension appears in the sidebar after a page refresh.
9

Enable demo mode

If you don’t have a Pastures Engine instance, enable Demo Mode in Pastures → Settings to work with synthetic data. This lets you develop and test UI changes without a backend.

​
Common Issues

If yarn serve-pkgs fails with a port conflict, ensure no other process is using port 4500. You can check with lsof -i :4500.
ProblemSolution
ERR! engine during installAdd --ignore-engines to the install command
Extension not visible in RancherRefresh the page; confirm serve-pkgs is running and accessible
API calls failingEnable demo mode in Settings or configure a valid Engine URL