diff --git a/docs/Debugging.md b/docs/Debugging.md
new file mode 100644
index 0000000..2d6d6ee
--- /dev/null
+++ b/docs/Debugging.md
@@ -0,0 +1,112 @@
+### How to Debug PiPedal.
+
+PipPedal consists of the following subprojects:
+
+*    A web application build in React, found in the react subdirectory.
+
+*    `pipedald`: a Web server, written in C++, serving a web socket, and pre-built HTML components from the React app.
+     All audio services are provided by the pipedal process.
+
+*   `pipedalshutdownd`: A service to execute operations that require root credentials on behalf of pipedald. (e.g. shutdown, reboot,
+    and pushing configuration changes).
+
+*   `pipedalconfig`: A CLI utility for managing and configuring the pipedald services.
+     
+*   `pipedaltest`: Test cases for pipedald, built using the Catch2 framework.
+
+
+You must stop the pipdeal service before launching a debug instance of pipedald:
+
+    sudo systemctl stop pipedald
+
+or
+
+    pipedalconfig -stop  #Stops the Jack service as well.
+
+But there's no harm in running a debug react server that's configured to connect to the web 
+socket of a production instance of pipedal on port 80, if you aren't planning to debug C++ code.
+
+In production, the pipedald web server serves the PiPedal web socket, as well as static HTML from the  built 
+react components. But while debugging, it is much more convenient to use the React debug server for 
+React sources, and configure pipedald to serve only the websocket. 
+
+To start the React debug server, from a shell, cd to the react directory, and run "./start". The react debug 
+server will detect any changes to React sources, and rebuild them automatically (no build step required). 
+Actual debugging is performed using the Chrome debugger (which is remarkably well integrated with React).
+
+To get this to work on Raspberry Pi, you will probably have to make a configuration change.
+
+Edit the file `/etc/sysctl.conf`, and add or increase the value for the maximum number of watchable user 
+files:
+
+    fs.inotify.max_user_watches=524288
+
+followed by `sudo sysctl -p`. Note that VS Code and the React framework both need this change.
+
+By default, the React app will attempt to contact the pipedal server on ws:*:8080 -- the address on which
+the debug version of systemctld listens on. This can be reconfigured
+in the file react/src/public/var/config.json if desired. If you connect to the the pipedald server port, pipedald intercepts requests for this file and 
+points the react app at itself, so the file has no effect when running in production. 
+
+The React app will display the message "Error: Failed to connect to the server", until you start the pipedal websocket server in the VSCode debugger. It's quite reasonable to point the react debug app at a production instance of the pipedal server instead.
+
+    react/public/var/config.json: 
+    {
+        ...
+        "socket_server_port": 80,
+        "socket_server_address": "*",
+        ...
+    }
+
+Setting socket_server_address to "*" configures the web app to reconnect using the host address the browser
+request used to connect to the web app. (e.g. 127.0.0.1, or pipedal.local, &c). If you choose to provide an explicit address,
+remember that it is to that address that the web browser will connect.
+
+The original development for this app was done with Visual Studio Code. Open the root project directory in
+Visual Studio Code, and it will detect the CMake build files, and configure itself appropriately. Wait for 
+the CMake plugin in Visual Studio Code to configure itself, after loading. 
+
+Once CMake has configured itself, build and debug commands are available on the CMake toolbar at the 
+bottom of the Visual Studio Code window. Set the build variant to debug. Set the debug target to "pipedald". 
+Click on the Build button to build the app. Click on the Debug button to launch a debugger.
+
+To get the debugger to launch and run correctly, you will need to set commandline parameters for pipedald. 
+Commandline arguments can be set in the file .vscode/settings.json: 
+
+    {
+        ...
+        "cmake.debugConfig": {
+            "args": [
+            "<projectdirectory>/debugConfig","<projectdirectory>/build/react/src/build",  "-port", "0.0.0.0:8080"
+            ],
+
+        ...
+    }
+
+where `<projectdirectory>` is the root directory of the pipedal project.
+
+The default debug configuration for pipedal is configured to use /var/pipedal for storing working data files, 
+which allows it to share configuration with a production instance of pipedal. Be warned that the permissioning 
+for this folder is intricate. If you plan to use the data from a production server, get the production server 
+installed first so the permissions are set correctly. If you install a production instance later, remove the 
+entire directory before doing so, to ensure that none of the files in that directory are permissioned 
+incorrectly. 
+
+You will need to add your userid to the pipedal_d group if you plan to share the /var/pipedal directory. 
+     
+     sudo usermod -a -G pipedal_d *youruserid*
+
+You will need to add your userid to the bluetooth group if you plan to debug Bluetooth onboarding code.
+
+    sudo usermod -a -G bluetooth *youruserid*
+
+
+Or you can avoid all of this, by configuring the debug instance to use a data folder in your home directory. Edit 
+`debugConfig/config.json`:
+
+    {
+        ...
+        "local_storage_path": "~/var/pipedal",
+        ...
+    }
+