Improved local installation documentation (#585)

* Update docker-compose.md (#501) fix path error for restAPI image * Update changelog.md * Added more detailed installation and local dev document * edits to installation setup * update local-dev.md and readme.md --------- Co-authored-by: Mike Cunningham <[email protected]> Co-authored-by: Jared Ondricek <[email protected]> Co-authored-by: Erin Hall <[email protected]>
center-for-threat-informed-defense · Jan 13, 2025 · 1a0cfda · 1a0cfda
1 parent 0082edb
commit 1a0cfda
Show file tree

Hide file tree

Showing 2 changed files with 148 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@ The ATT&CK Workbench application is made up of several repositories. For the ful
 The manual install instructions in each repository describe how each component to be deployed to a separate machine or with customized settings. 
 
 ### Installing using Docker
-Please refer to our [Docker install instructions](docs/docker-compose.md) for information on installing and deploying the the full application using Docker. The docker setup is the easiest way to deploy the application.
+Please refer to our [Docker install instructions](docs/docker-compose.md) for information on installing and deploying the full application using Docker. The docker setup is the easiest way to deploy the application.
 
 ### Manual Installation
 
@@ -94,6 +94,10 @@ To allow for additional customization, the ATT&CK Workbench enables users to set
 
 For additional troubleshooting and installation of security certificates for use by ATT&CK Workbench, pleaser refer to [PKI Certificates instructions](docs/certs.md).
 
+### Developer Setup
+
+Please refer to our [local development instructions](docs/local-dev.md) for information on installing and running the application for local development and testing. 
+
 ## Related Work
 
 ### STIX

diff --git a/docs/local-dev.md b/docs/local-dev.md
@@ -0,0 +1,143 @@
+# Local Development Documentation
+
+This document outlines how to set up ATT&CK Workbench for local development. For information on installing and deploying the full application using Docker, please refer to the [docker install instructions](https://github.com/center-for-threat-informed-defense/attack-workbench-frontend/blob/master/docs/docker-compose.md).
+
+## Prerequisites
+
+Before running the application locally, ensure you have the following set up:
+
+1. Clone the required repositories
+    - [attack-workbench-frontend](https://github.com/center-for-threat-informed-defense/attack-workbench-frontend) repository
+    - [attack-workbench-rest-api](https://github.com/center-for-threat-informed-defense/attack-workbench-rest-api) repository alongside the frontend
+
+2. Install [Node.js](https://nodejs.org/) v18 or greater
+
+3. Install MongoDB
+
+    Follow the official [MongoDB installation guide](https://www.mongodb.com/docs/manual/installation/) to install MongoDB on your operating system.
+
+
+## Configure and Run the REST API
+
+#### 1. Install dependencies
+
+Navigate to the `attack-workbench-rest-api` directory and run
+
+```
+npm install
+```
+
+#### 2. Configure the system
+
+Configure the application using environment variables, a configuration file, or a combination. Please refer to the documentation on how to [Configure the System](https://github.com/center-for-threat-informed-defense/attack-workbench-rest-api?tab=readme-ov-file#step-3-configure-the-system) for more details.
+
+For example, you can use a custom configuration to adapt to your specific environment:
+
+- Create a `.rest-api-env` file:
+
+    ```bash
+    export DATABASE_URL=mongodb://localhost/attack-workspace
+    export JSON_CONFIG_PATH="resources/sample-configurations/multiple-apikey-services.json"
+    export WB_REST_SERVICE_ACCOUNT_CHALLENGE_APIKEY_ENABLE=true
+    export NODE_EXTRA_CA_CERTS="path/to/cert.crt"    
+    ```
+
+- Ensure this file is sourced when starting the backend:
+
+    ```bash
+    source .rest-api-env
+    ```
+
+#### 3. Run the REST API
+
+```
+node ./bin/www
+```
+
+Or to run it in the background:
+
+```
+node ./bin/www &
+```
+
+## Setting Up the Frontend
+
+#### 1. Install dependencies
+
+Navigate to the `attack-workbench-frontend/app` directory and run
+
+```
+npm install
+```
+
+#### 2. Run the frontend locally
+
+```
+ng serve
+```
+
+Open your browser and navigate to `http://localhost:4200`
+
+
+## Note: Recommended setup using Visual Studio Code Workspaces
+
+To streamline your development workflow, you can configure a Visual Studio Code workspace for easier management of both the frontend and REST API repositories. Open VS Code in the `attack-workbench-frontend` directory, add the directory for the REST API repository, and save the workspace.
+
+To automate terminal setups, ensure the "Restore Terminals" extension is installed in VS Code. Open the `.code-workspace` file in a text editor other than VS Code and configure the `restoreTerminals.runOnStartup` and `restoreTerminals.terminals` settings.
+
+Example VS Code Workspace configuration:
+
+```json
+{
+    "folders": [
+        {
+            "name": "attack-workbench-rest-api",
+            "path": "attack-workbench-rest-api"
+        },
+        {
+            "name": "attack-workbench-frontend",
+            "path": "attack-workbench-frontend"
+        }
+    ],
+    "settings": {
+        "terminal.integrated.env.osx": {
+            "DATABASE_URL": "mongodb://localhost/attack-workspace",
+            "JSON_CONFIG_PATH": "resources/sample-configurations/multiple-apikey-services.json",
+            "WB_REST_SERVICE_ACCOUNT_CHALLENGE_APIKEY_ENABLE": "true",
+            "NODE_EXTRA_CA_CERTS": "path/to/cert.crt" 
+        },
+        "restoreTerminals.runOnStartup": true,
+        "restoreTerminals.terminals": [
+            {
+                "splitTerminals": [
+                    {
+                        "name": "rest-api",
+                        "commands": [
+                            "cd ../attack-workbench-rest-api/",
+                            "git checkout develop",
+                            "git pull",
+                            "npm ci",
+                            "source /path/to/.rest-api-env",
+                            "node bin/www"
+                        ]
+                    }
+                ]
+            },
+            {
+                "splitTerminals": [
+                    {
+                        "name": "frontend",
+                        "commands": [
+                            "cd ../attack-workbench-frontend/app/",
+                            "git checkout develop",
+                            "git pull",
+                            "npm ci",
+                            "ng serve --open"
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+}
+```