Merge pull request #320 from bookbrainz/document-local-setup

docs: Document local setup and debugging with VSCode
metabrainz · Nov 28, 2019 · d47b2fc · d47b2fc
2 parents f7e54d0 + 9a4f180
commit d47b2fc
Show file tree

Hide file tree

Showing 6 changed files with 166 additions and 97 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,54 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch Program",
+            "env": {"SSR":true},
+            "program": "${workspaceFolder}/lib/server/app.js",
+            "sourceMaps": true,
+            "preLaunchTask": "build-website"
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Webserver Mocha Tests",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "args": [
+                "--timeout", "999999",
+                "--colors",
+                // You can point to a specific file or folder to run only those tests
+                "${workspaceFolder}/test/"
+            ],
+            "env": {"NODE_ENV":"test","SSR":true},
+            "internalConsoleOptions": "openOnSessionStart",
+            "preLaunchTask": "build-website"
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "Launch API",
+            "program": "${workspaceFolder}/lib/api/app.js",
+            "preLaunchTask": "build-api-with-sourcemaps"
+        },
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "API Mocha Tests",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "args": [
+                "--timeout", "999999",
+                "--colors",
+                // If you want to run only on test file, put the path here:
+                "${workspaceFolder}/test/src/api/routes/test-search.js"
+            ],
+            "env": {"NODE_ENV":"test","SSR":true},
+            "internalConsoleOptions": "openOnSessionStart",
+            "preLaunchTask": "build-api-with-sourcemaps"
+        }
+    ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,5 @@
+{
+    "typescript.format.enable": false,
+    "javascript.validate.enable": false,
+    "eslint.enable": true
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -0,0 +1,52 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build-website",
+            "dependsOn": [
+                "build-server-with-sourcemaps",
+                "build-client-js"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "build-server-with-sourcemaps",
+            "command": "${workspaceFolder}/node_modules/.bin/babel",
+            "args": [
+                "src",
+                "--out-dir",
+                "lib",
+                "--source-maps",
+                "--ignore src/api"
+            ],
+            "isBackground": false
+        },
+        {
+            "label": "build-client-js",
+            "type": "npm",
+            "script": "build-client-js",
+            "problemMatcher": [],
+        },
+        {
+            "label": "build-api-with-sourcemaps",
+            "command": "${workspaceFolder}/node_modules/.bin/babel",
+            "args": [
+                "src",
+                "--ignore 'src/server','src/client'",
+                "--source-maps",
+                "--out-dir",
+                "lib"
+            ],
+            "isBackground": false
+        },
+        {
+            "label": "lint-code",
+            "type": "npm",
+            "script": "lint",
+            "problemMatcher": []
+        }
+    ]
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ please follow the steps below.
 
 ## Bug Tracker
 
-We use the bug tracker at https://tickets.metabrainz.org to track issues with
+We use the bug tracker at https://tickets.metabrainz.org/projects/BB to track issues with
 the site or supporting BookBrainz libraries. If you find a problem, or are
 looking for something to fix, please head there. We do not use GitHub issues.
 

diff --git a/NODEJS_SETUP.md b/NODEJS_SETUP.md
@@ -3,7 +3,7 @@
 ### These instruction are only valid for specific cases when you do not want to use Docker (`./develop.sh`) to run the server on your machine.
 
 If for some reason you do not want to use our standard development environment (Docker), you can run the server code manually (
-regardless of whether you are running dependencies with Docker for the database and search  or you [installed them manually](./MANUAL_INSTALL.md))
+regardless of whether you are running dependencies (database, search,…) with Docker or you [are running them manually](./MANUAL_INSTALL.md))
 
 ## Installing NodeJS
 
@@ -21,93 +21,63 @@ This command will also compile the site LESS and JavaScript source files.
 ## Configuration
 
 Our `config.example.json` is set up to work out of the box running everything in Docker. Adresses for the dependencies refer to docker container names, so that containers can communicate with each other.
+
 You will need to modify the `config/config.json` file* to point to the dependencies from outside the Docker network.
-For example, set `session.redis.host`, `database.connection.host` and `search.search` to point to `localhost` (or wherever your dependencies are running) and adjust the ports accordingly.
+Typically, you'll want to set `session.redis.host` and `database.connection.host` to `localhost` and `search.host` to `localhost:9200`  and adjust the ports according to your setup.
 
-*If it doesn't exist, make a copy of `config.example.json` and rename it) 
+*If it doesn't exist, make a copy of `config.example.json` and rename it)
 
 ## Building and running
 A number of subcommands exist to manage the installation and run the server.
 These are described here; any commands not listed should not be called directly:
 
 * start - start the server in production mode, with code built once
-* debug - start the server in debug mode, with code watched for changes
+* [debug - start the server in debug mode, with code watched for changes](#watch-files-and-live-reload-with-webpack)
 * lint - check the code for syntax and style issues
 * test - perform linting and attempt to compile the code
 * jsdoc - build the documentation for JSDoc annotated functions within the
   code
 
-# VSCode users
-If you want to use VSCode to run and debug the server or API, here is a VSCode launch configuration for running both the server and the tests, useful in both cases to debug into the code.
-Here is [a good introduction](https://www.youtube.com/watch?v=yFtU6_UaOtA) to debugging javascript in VSCode
-1. At the root fo the repository, create a .vscode/launch.json file containing:
-  ```
-  {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Launch Program",
-            "env": {"SSR":true},
-            "program": "${workspaceFolder}/lib/server/app.js",
-            "sourceMaps": true,
-            "preLaunchTask": "build-server-with-sourcemaps"
-        },
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Mocha Tests",
-            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
-            "args": [
-                "--timeout", "999999",
-                "--colors",
-                "${workspaceFolder}/test/" // You can point to a specific file or folder to run only those tests
-            ],
-            "env": {"NODE_ENV":"test","SSR":true},
-            "internalConsoleOptions": "openOnSessionStart",
-            "preLaunchTask": "build-server-with-sourcemaps"
-        }
-    ]
-}
-  ```
-2. Create a .vscode/tasks.json file containing:
-  ```
-{
-    "version": "2.0.0",
-    "tasks": [
-        {
-            "label": "build-server-with-sourcemaps",
-            "command": "${workspaceFolder}/node_modules/.bin/babel",
-            "args": [
-                "src",
-                "--out-dir",
-                "lib",
-                "--source-maps"
-            ],
-            "isBackground": false
-		},
-		{
-			"label": "build-client",
-            "type": "npm",
-            "script": "build-client-js",
-            "problemMatcher": [],
-			"isBackground": false,
-		},
-		{
-			"label": "build-client-and server",
-            "type": "npm",
-            "script": "build",
-            "problemMatcher": [],
-			"isBackground": false,
-        }
-    ]
-}	
- ```
+<br/>
+
+# Debugging with VSCode
+You can use VSCode to run the server or API and take advantage of its debugger, an invaluable tool I highly recommend you learn to use.
+
+This will allow you to put breakpoints to stop and inspect the code and variables during its execution, advance code execution line by line and step into function calls, instead of putting `console.log` calls everywhere.
+
+Here is [a good introduction](https://www.youtube.com/watch?v=yFtU6_UaOtA) to debugging javascript in VSCode.
+
+There are VSCode configuration files (in the `.vscode` folder) for running both the server and the tests, useful in both cases to debug into the code and see what is happening as the code executes.
+Make sure the dependencies (postgres, redis, elasticsearch) are running, and you can just open the debugger tray in VSCode, select 'Launch Program' and click the button!
 
 BookBrainz uses [Flow](https://flow.org) as a javascript typechecking library. VSCode is partial to Typescript, and needs to be configured to avoid confusion.
 We recommend you install the flow-for-vscode extension and [follow this setup step](https://github.com/flowtype/flow-for-vscode#setup):
 `Set [VSCode configuration] javascript.validate.enable option to false or completely disable the built-in TypeScript extension for your project`
+
+<br/>
+
+# Watch files and live reload with Webpack
+
+Advanced users may want to use Webpack to build, watch files and inject rebuilt pages without having to refresh the page,
+keeping the application state intact, for the price of increased compilation time and resource usage (see note below).
+
+If you are running the server manually, you can simply run `npm run debug` in the command line.
+
+If you're using Docker and our `./develop.sh` script, you will need to modify the `docker-compose.yml` file to:
+1. change the `command` to:
+    - `npm run debug` if you only want to change client files (in `src/client`)
+    - `npm run debug-watch-server` if you *also* want to modify server files (in `src/server`)
+2. mount the `src` folder
+
+For example:
+```
+services:
+  bookbrainz-site:
+  # 1. Change the command to run
+    command: npm run debug
+    volumes:
+      - "./config/config.json:/home/bookbrainz/bookbrainz-site/config/config.json:ro"
+  # 2. Mount the src directory
+      - "./src:/home/bookbrainz/bookbrainz-site/src"
+```
+**Note**: Using Webpack watch mode (`npm run debug`) results in more resource consumption (about ~1GB increased RAM usage) compared to running the [standard web server](/README.md#running-the-web-server).
diff --git a/README.md b/README.md
@@ -27,6 +27,12 @@ directories will exist:
   (`src/client/stylesheets`).
 * `static/js` - minified JavaScript files which are referred to by the site
   pages.
+
+## Contributing
+We welcome any and all contributions ! Whether you want to add or improve entries on [bookbrainz.org](https://bookbrainz.org), fix an issue on the website or provide new functionnality, we'll be happy to have your help and count you part of our ranks !
+If you are new to open source contribution workflows, have a look at [this beginner's guide](https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/) and our [contribution guidelines](CONTRIBUTING.md).
+Looking for existing issues, or to report a new bug you found? Head to our ticket tracker at https://tickets.metabrainz.org/projects/BB !
+Still not sure what to start with? Have a look at [tickets tagged **good-first-bug**](https://tickets.metabrainz.org/issues/?jql=project%20%3D%20BB%20AND%20status%20in%20(Open%2C%20Reopened)%20AND%20resolution%20%3D%20Unresolved%20AND%20labels%20%3D%20good-first-bug%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC)
 
 ## Documentation
 
@@ -126,32 +132,14 @@ Point you browser to `localhost:9099/1/api-docs` to pull up the documentation an
 Don't forget to run `./stop.sh` once you are done developing to stop the dependencies that are running in the background.
 
 
-## Advanced users
+## Advanced users and debugging
 
-If you do not want to use Docker, you can instead [install the database and search dependencies on your machine](./DEPENDENCIES_MANUAL_INSTALL.md),
-and/or [run the NodeJS server locally](./NODEJS_SETUP.md) while using dockerized dependencies.
-Running the NodeJS server locally would be easier if you want to use a debugger, for instance.
+Once you get into serious work on the project, we recommend you use a debugger and [run the NodeJS server locally](./NODEJS_SETUP.md) (while still running dependencies in Docker for simplicity).
+Using a debugger will allow you to pause and inspect the server code as it is being executed.
 
------------
-Advanced users may want to use Webpack to build, watch files and inject rebuilt pages without having to refresh the page,
-keeping the application state intact, for the prie of a longer compilation time.
+If you do not want to use Docker at all, you can also [install the database and search dependencies on your machine](./DEPENDENCIES_MANUAL_INSTALL.md)
 
-For that, you will need to modify the `docker-compose.yml` file to mount the `src` folder and change the command to
-- `npm run debug` if you only want to change client files (in `src/client`)
-- `npm run debug-watch-server` if you *also* want to modify server files (in `src/server`)
 
-For example:
-```
-services:
-  bookbrainz-site:
-    command: npm run debug
-    volumes:
-      - "./config/config.json:/home/bookbrainz/bookbrainz-site/config/config.json:ro"
-      - "./src:/home/bookbrainz/bookbrainz-site/src"
-```
-**Note**: Using Webpack watch results in more resource consumption (about ~1GB increased RAM usage) compared to running the [standard web server](#running-the-web-server).
-<br/>
-<br/>
 
 # Testing
 The test suite is built using Mocha and Chai. Before running the tests, you will need to set up a `bookbrainz_test` database in postgres. Here are the instructions to do so: