RSNewWebUI/README.md

Web Interface for Retroshare

A web-based frontend for Retroshare which communicates with the client through the JSON API.

Requirements

• Retroshare v0.6.5+ with JSON API enabled(see instructions below)
• A modern JavaScript-enabled web browser
• Node.js 24 LTS or newer and npm when building from SCSS sources
• A POSIX-compatible sh on Linux or macOS
• qmake (optional packaging integration)

Installation

Note: The Web Interface is shipped by default in the latest release of Retroshare. If you want to customise it or contribute to it then proceed with the following steps.

Install WebUI

First, you need to download and install the web interface javascript code itself:

1. Clone the repo: You can clone using git, or download the zip file and extract it

   git clone https://github.com/Retroshare/RSNewWebUI
   cd RSNewWebUI
   

2. Build the files: If you have qmake installed, you need to run this command from the repository root to build it:

   qmake .
   

   qmake packages the committed generated webui-src/styles.css. Without qmake, run the shell build script instead:

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

   On Windows, use the batch script to bundle the checked-in generated files:

   webui-src\make-src\build.bat
   

Compile Retroshare with JSON API

If you are on older versions of Retroshare then it needs to be compiled with non-default options as follows:

qmake CONFIG+="debug rs_jsonapi rs_webui"
make

See the RetroShare repo for more detailed instructions on compiling RetroShare. You should afterwards see a tab 'JSON API' and a tab 'Web Interface' in the Preferences.

Enable JSON API

You need to enable the JSON API, through which the web interface communicates with the client:

1. Open Retroshare, go to Preferences > JSON API.
2. Make sure the Enable Retroshare JSON API Server box is checked.

Enable Web Interface

1. Go to Preferences > Webinterface.
2. Make sure the Enable Retroshare WEB Interface box is checked.
3. Enter a password to protect access to the web interface.

If necessary, point the Web interface directory to the place where the webui files are compiled. This is usually RSNewWebUI/webui/.

In any case, click on "Apply settings" after making the changes. If everything goes ok, you should see a new token webui:[your password] under the Authenticated Tokens section in the JSON API preferences page.

Usage

Basic Usage

This is the default link to access the WebInterface.
Open this link your browser -> https://localhost:9092/index.html.

Note: If you changed the port in the JSON API preferences pages, the port in the above line needs to be changed accordingly.

Advanced Usage

The Web interface is only accessible from localhost (127.0.0.1). If you want to access the web interface of a headless retroshare server, then you need to create a SSH tunnel as follows:

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

After that, the Web interface of the Retroshare running on 'server' is tunneled to your local machine and accessible through localhost:9092.

Running a headless retroshare server is one possibility. The Webinterface however does not allow you to create new nodes. Therefore the steps are:

1. Create a node using the standard Qt UI. That can be done in another machine.
2. Copy the retroshare data directory (.retroshare/ on linux) on the server.
3. On the server, launch a headless retroshare using that node:

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

After that follow instructions to launch your profile (you need to choose a webui password and enter the ID and login password of your node).

Contributing

Setup

Development requires Node.js 24 or newer, npm, sh on macOS or Linux, and a RetroShare instance with the JSON API and Web Interface enabled for manual testing.

Fork and clone the repository, then install the locked dependencies:

cd RSNewWebUI/webui-src
npm ci

Source and generated files

Edit files under webui-src/app/, including SCSS under webui-src/app/scss/. Do not edit these generated files by hand:

• webui-src/styles.css is generated from webui-src/app/scss/main.scss.
• webui/app.js, webui/styles.css, and webui/index.html are build output.

webui-src/app/mithril.js is the vendored Mithril 2.3.8 runtime. Replace it only during an intentional Mithril upgrade.

Build and test

From webui-src/, compile SCSS and create the deployable webui/ directory:

npm run build
npm run lint

These npm commands use build.bat on native Windows and build.sh on other platforms.

Commit SCSS changes together with the regenerated webui-src/styles.css. qmake . packages that committed CSS but does not compile SCSS. Running make alone does not rebuild this TEMPLATE = subdirs project; rerun qmake . from the repository root when using qmake.

The shell bundler works without Node.js, but only copies the existing CSS. Run it from webui-src/ with sh:

sh make-src/build.sh

For focused rebuilds, run these commands from webui-src/:

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

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

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

npm run watch recompiles SCSS into webui-src/styles.css; it does not copy the CSS into webui/ or rebuild JavaScript. Use the CSS-only command above when testing watched changes through RetroShare.

Before submitting, run the full build and lint commands, then point RetroShare's Web interface directory at webui/ and manually test the affected screens. ESLint, generated JavaScript syntax, the build dispatcher, and shell syntax on non-Windows systems are checked by npm run lint; no formatting script is defined.

References

Now, While contributing you can checkout these resources as you might need to look up for these often.

• mithril

• You can list files with @jsonapi in libretroshare/src/retroshare of retroshare:

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

---

And, that's it. You are more than welcome to contribute to this project. If you have any questions/difficulties in setting up or running the project, you can raise an issue and we will be more than willing to help you out.

Bug Reports & Feature requests

Please create an issue concisely describing the bug you faced, or the feature you would like to see implemented.

Development

Whether you are a JavaScript developer or a Web designer, you can help make the web interface better. Get in touch with us on the Developer forums in Retroshare.