RetroShare Web Interface

This project is the browser interface for RetroShare. It talks to RetroShare through its JSON API.

Recent RetroShare releases already include this interface. Follow this guide if you want to build it yourself, change it, or contribute to it.

What you need

• RetroShare 0.6.5 or newer, with the JSON API enabled
• A modern web browser

Set up RetroShare

Enable the JSON API

1. Open RetroShare.
2. Go to Preferences > JSON API.
3. Enable RetroShare JSON API Server.

Enable the Web Interface

1. Go to Preferences > Web Interface.
2. Enable the Web Interface.
3. Choose a password.
4. Set Web interface directory to this repository's webui/ directory if RetroShare does not find it automatically.
5. Click Apply.

The JSON API page should now show an authenticated token named webui:<your password>.

Open the interface

Open https://localhost:9092/index.html in your browser. If you changed the JSON API port, replace 9092 with that port.

Connect to a remote or headless server

The Web Interface listens on localhost by default. To reach RetroShare on a remote server, run this command on your local computer:

ssh -L 9092:localhost:9092 -N login@server

Keep that command running, then open https://localhost:9092/index.html.

The Web Interface cannot create a new RetroShare node. Create the node with the desktop interface first, then copy its RetroShare data directory to the server. On Linux this directory is usually .retroshare/.

Start the service on the server with:

./retroshare-service/src/retroshare-service -U list -W

Follow the prompts to select the profile and enter its passwords.

Contributing

To work on the source, you need:

• Node.js 24 or newer and npm
• sh on macOS or Linux; Windows uses the included batch file
• qmake only if you want to use RetroShare's qmake build integration

First-time setup

Fork the repository, clone your fork, and install the locked dependencies:

git clone https://github.com/YOUR-USERNAME/RSNewWebUI.git
cd RSNewWebUI/webui-src
npm ci

Where to make changes

• JavaScript source is in webui-src/app/.
• SCSS source is in webui-src/app/scss/.
• webui-src/styles.css is generated from app/scss/main.scss. Do not edit it by hand, but commit it with the SCSS changes that generated it.
• Everything in webui/ is build output. Do not edit those files by hand.
• webui-src/app/mithril.js contains Mithril 2.3.8. Change it only when intentionally upgrading Mithril.

Normal development commands

Run these commands from webui-src/:

npm run build
npm run lint

npm run build compiles the SCSS and creates the complete webui/ directory. It automatically uses build.bat on Windows and build.sh on macOS or Linux.

npm run lint checks the source files and does not require webui/ to exist.

To rebuild CSS whenever an SCSS file changes, run:

npm run watch

Watch mode updates webui-src/styles.css only. Run npm run build when you also need to update the files in webui/.

Using qmake during development

Run qmake from the repository root:

qmake .

qmake copies the committed webui-src/styles.css; it does not compile SCSS. After changing SCSS, run npm run build first. Rerun qmake . when you need qmake to package newer WebUI files; make alone does not do that for this project.

A standalone checkout may show a warning about a missing ../retroshare.pri. The WebUI files are still generated.

Building without npm or qmake

These commands create webui/ from the files already stored in the repository. They do not compile SCSS.

From the repository root on macOS or Linux:

sh webui-src/make-src/build.sh

From the repository root on Windows:

webui-src\make-src\build.bat

Optional focused builds

The normal npm run build command is the easiest choice. On macOS or Linux, you can rebuild only one generated file from webui-src/:

# JavaScript only
sh make-src/build.sh "" app.js

# HTML only
sh make-src/build.sh "" index.html

# CSS only
./node_modules/.bin/sass --no-source-map --style=compressed app/scss/main.scss styles.css
sh make-src/build.sh "" styles.css

Before opening a pull request

1. Run npm run build.
2. Run npm run lint.
3. Point RetroShare's Web interface directory to this repository's webui/ directory.
4. Manually test the screens you changed.
5. If you changed SCSS, include the regenerated webui-src/styles.css.

There is no separate formatting command.

Building older RetroShare versions

If you are testing with an older RetroShare version, you may need to build it with the JSON API and WebUI enabled:

qmake CONFIG+="debug rs_jsonapi rs_webui"
make

See the RetroShare repository for complete build instructions. After building, RetroShare preferences should contain both JSON API and Web Interface pages.

Useful references

• Mithril documentation
• RetroShare source

To find RetroShare headers that expose JSON API methods, run this from libretroshare/src/retroshare/ in the RetroShare source tree:

grep -c "@jsonapi" *.h | grep -v ":0"

Get help or report a problem

Open a GitHub issue and briefly explain what happened, what you expected, and how someone can reproduce it. You can also join the RetroShare developer forums to discuss development.