1 files changed, 105 insertions, 1 deletions
diff --git a/docs/hacking/uidev.rst b/docs/hacking/uidev.rst
index 4ada825e..968fa010 100644
--- a/docs/hacking/uidev.rst
+++ b/docs/hacking/uidev.rst
@@ -3,4 +3,108 @@
 Bitmask's Javascript User Interface
 ====================================
 
-(stuff goes here).
+Some notes specific to development of the javascript ui interface. For more detail, see ``ui/README.md``.
+
+Run headless backend in development mode
+----------------------------------------
+
+Prerequisites::
+
+.. note: move this snippet to a common include!
+
+  sudo apt install build-essential python-dev python-virtualenv \
+                   libsqlcipher-dev libssl-dev libffi-dev
+
+Install and activate a virtualenv::
+
+  cd bitmask-dev
+  virtualenv venv
+  source venv/bin/activate
+
+(Refer to the `virtualenv documentation` if you're not using bash/zsh/dash).
+
+All the subsequent commands assume that you have activated the virtualenv.
+
+Install all the python dependencies::
+
+  make dev-backend
+
+Run application::
+
+  bitmaskd
+
+.. _`virtualenv documentation`: https://virtualenv.pypa.io/en/stable/userguide/#activate-script
+
+Run user interface frontend
+---------------------------
+
+If you want to run the Bitmask user interface, you additionally need the
+following:
+
+Prerequisites::
+
+  sudo apt install python-pyqt5  python-pyqt5.qtwebkit
+
+Install python dependencies::
+
+  make dev-all
+
+Note: even though the UI is in javascript, Qt is used to create a webview
+window.
+
+Run user interface::
+
+  bitmask
+
+The command `bitmask` should be in your path if you have activated the virtual
+environment.
+
+Install Bitmask user interface in development mode
+--------------------------------------------------
+
+The above instructions will install a python package that contains a pre-
+bundled version of the javascript UI.
+
+If you want to modify the javascript UI, then you need to be able to update the
+javascript bundle whenever a javascript or CSS source file changes. To support
+this, we build a python package of the javascript UI and install it in
+"development mode" so that changes to the contents of the package are reflected
+in bitmaskd immediately.
+
+Prerequisites::
+
+  sudo apt install nodejs npm nodejs-legacy
+
+Next, run ``dev-install``::
+
+  cd ui
+  make dev-install
+
+Now you should be able to run the user interface with debugging tools::
+
+  bitmaskd
+  cd ui
+  npm run ui
+
+This command is the same as running::
+
+  chromium-browser "http://localhost:7070/#$(cat ~/.config/leap/authtoken)"
+
+Firefox does not work as well, because the UI is only tested with webkit-based
+browsers.
+
+Chromium is not the most ideal, however, because it uses a newer webkit than is
+available in Qt. Instead, try qupzilla::
+
+  sudo apt install qupzilla
+  bitmaskd
+  qupzilla -ow "http://localhost:7070/#$(cat ~/.config/leap/authtoken)"
+
+If you make a change to any of the CSS or JS source files, you need to rebuild
+the javascript bundle. You can do this continually as files change like so::
+
+  cd ui
+  node run watch
+
+The new javascript bundle will be used when you refresh the page so long as
+``make dev-install`` was previously run.