polkadot-js/apps: Running a Polkadot Node Interface Locally

What polkadot-js/apps Gives Polkadot and Substrate Users

polkadot-js/apps solves the problem of accessing a Polkadot or Substrate node without requiring users to assemble a separate frontend for each chain. The repository README describes the project as a portal into the networks and as the main user-facing application for their available features. Its intended audience includes people who already operate or want to connect to one of the supported chains, plus chain developers who need to adapt the interface to a network.

The project is not a blockchain node. The local startup instructions explicitly assume that a Polkadot Node is already running. That boundary matters because the application is the view and interaction layer, while chain data and node operations remain external. The Docker example makes this separation visible through `WS_URL`: the container receives a WebSocket address rather than starting a chain itself.

Three delivery forms are documented. The standard application is hosted at `https://polkadot.js.org/apps/`. An IPFS version is available through a content hash or IPNS, and the Electron application uses the same features with different account storage. This makes deployment choice part of the product design rather than a separate implementation project.

Workspace Packages and Chain-Specific Configuration

Based on the repository layout, the root project is organized as a Yarn workspace with application packages under `packages/*`. The root `package.json` identifies `packages/apps-electron/build/electron.js` as the package entry point and defines separate build scripts for the web and Electron outputs. The browser portal, localization assets, shared application code, and Electron wrapper can therefore evolve within one repository without being treated as unrelated applications.

Chain integration has a separate control surface. The README directs chain developers to `packages/apps-config` for API types, settings, and logos. This is the key extension mechanism for a new or modified Substrate chain. It is configuration-driven from the user interface's perspective, so adding support does not require every network detail to be hard-coded into the main application.

The repository also includes localization tooling, Docker files, type and build configuration, and an `.env-example`. These entries indicate that localization, production builds, and container deployment are first-class parts of the project. However, the README does not document a public extension API or a formal compatibility policy between a particular polkadot-js/apps version and every possible Substrate runtime. Adopters should therefore treat `packages/apps-config` customization as a code change that must be reviewed alongside the target chain.

Local Setup from Clone to localhost:3000

For development, the README requires Yarn workspaces and warns against npm because it says npm will produce broken dependencies. There is a version discrepancy worth resolving before cloning: the README recommends Node.js 16 or newer and Yarn 1.22 or newer, while the root `package.json` declares `node >=18.14` and `packageManager` as `[email protected]`. The package manifest is the stricter and more specific source, so the commands below follow it.

After cloning, install the locked dependency set. The frozen lockfile keeps the install aligned with the versions recorded by the repository rather than resolving updates during installation:

git clone https://github.com/polkadot-js/apps <optional local path>

That command creates the local checkout. Change into the resulting repository directory before running the Yarn commands.

yarn install --frozen-lockfile

A successful installation prepares all workspace packages listed under `packages/*`. The next command starts the development server:

yarn run start

The README says to open `http://localhost:3000` after startup. The interface should be available there, but useful node-backed pages depend on a reachable local Polkadot Node. If the UI loads while chain data does not, the missing node connection is the first condition to investigate. The application can start without providing chain data itself.

Docker Deployment Against an Existing WebSocket Node

Docker is the documented deployment path when the frontend needs to be packaged as a container and connected to a node outside the container. The README uses the `jacogr/polkadot-js-apps:latest` image, passes `WS_URL`, publishes host port 80 to container port 80, and removes the container when it exits. The result is reachable at `http://localhost:80` or `http://localhost`.

Replace `someip` with the address of an actual accessible node endpoint. The repository does not supply the value because node location is environment-specific.

docker run --rm -it --name polkadot-ui -e WS_URL=ws://someip:9944 -p 80:80 jacogr/polkadot-js-apps:latest

If port 80 is already occupied, the README does not document an alternative mapping, so choosing a different deployment design would require verification rather than assuming an unsupported flag. The repository also documents how to build a container containing local changes:

docker build -t jacogr/polkadot-js-apps -f docker/Dockerfile .

This build does not start the node or prove that the configured endpoint is reachable. It packages the current workspace state. Connection routing, TLS, firewall rules, and node access policy remain deployment concerns outside the documented command.

IPFS Pinning and Its Release-Based Update Constraint

The hosted UI can also be distributed through IPFS, either by hash or through IPNS at `https://dotapps.io`. The README notes an important operational limit: the pinned UI only changes when a release occurs. Users who depend on an IPFS copy are therefore tied to release publication for content updates, even when the repository receives other changes.

An IPFS node can pin the release selected by `pin.json`. The documented command reads the hash, then adds it as a CID:

curl -s https://polkadot.js.org/apps/ipfs/pin.json | jq -jr .IpfsHash | xargs -0 -I CID ipfs pin add --progress CID

The README also provides a script that uses `/usr/local/bin/ipfs` and installs the same operation as `/usr/local/bin/polkadotjs-ipfs-pin.sh`. Pinning can then be scheduled through `crontab -e`; the documented entry runs at minute 0 of every hour. This automation checks and updates the pin, but the README does not describe integrity policy, rollback procedures, or how long each IPFS query may take.

For developers who need immediate visibility of local changes, the localhost build is the more direct option. IPFS distribution is better understood as a release-serving and content-addressing mechanism, not a continuous deployment channel.

Browser Accounts, Electron Storage, and Maintenance Boundaries

The Electron edition has one clearly documented difference from the web application: account storage. Browser accounts are held in browser local storage, while the desktop application stores encrypted accounts on the filesystem. The README associates local storage with XSS exposure and presents filesystem storage as avoiding that particular browser-storage risk. This is a project-specific architectural distinction, not a guarantee that every desktop attack is eliminated.

Account locations differ by operating system. macOS uses `~/Library/Application Support/polkadot-apps/polkadot-accounts`, Linux uses `~/.config/polkadot-apps/polkadot-accounts` or the `XDG_CONFIG_HOME` equivalent, and Windows uses `%APPDATA%\polkadot-apps\polkadot-accounts`. Operators should account for these paths during backup, migration, and desktop support.

The repository is not archived, and its last push was on 2026-09-29. Repository release records list `v0.171.1` on 2026-04-02, `v0.170.1` on 2026-02-24, and `v0.169.1` on 2025-11-26. The manifest version is `0.171.2`, while the listed releases do not include that version. For upgrades, teams should account for a large TypeScript workspace, `yarn.lock`, separate web and Electron builds, localization generation, and the need to retest chain-specific configuration. The Apache-2.0 license permits use and modification under its terms, but deployment, modification, and distribution remain subject to the license text.

Editorial conclusion

Adopt polkadot-js/apps when you need a configurable browser or Electron interface to a Polkadot or Substrate node, especially when chain developers need to change API types, settings, or logos in packages/apps-config. Do not choose it as a standalone chain client, because the README requires an available node. Before adoption, verify that your Node.js and Yarn versions match package.json, confirm that the target node exposes a reachable WebSocket endpoint, and review the account-storage distinction between the browser and Electron clients.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. polkadot-js/apps on GitHub
3. Project website
4. README
5. Releases