Running locally (#82)

* fix: typescript compilation for plugin-scaffolder-backend-aws-apps-for-backstage * fix: env vars not set when running backstage locally * docs: added website documentation for running backstage locally * fix: documentation typos --------- Co-authored-by: Anthony Watson <[email protected]> Co-authored-by: Jim McVea <[email protected]>
awslabs · Apr 2, 2024 · aa5f2b8 · aa5f2b8
1 parent 5b621d6
commit aa5f2b8
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 5 deletions.
diff --git a/backstage-plugins/plugins/scaffolder-backend-module-aws-apps/package.json b/backstage-plugins/plugins/scaffolder-backend-module-aws-apps/package.json
@@ -55,7 +55,8 @@
   },
   "devDependencies": {
     "@backstage/backend-common": "^0.20.0",
-    "@backstage/cli": "^0.25.0"
+    "@backstage/cli": "^0.25.0",
+    "@types/lodash": "^4.17.0"
   },
   "files": [
     "dist"

diff --git a/build-script/local-runners.sh b/build-script/local-runners.sh
@@ -9,16 +9,16 @@ start_local() {
 	echo "Starting a local PostgreSQL container"
 	docker compose -f $appRootDir/config/docker-compose.yml up --build --detach
 	echo "Starting the backstage app"
-	# set -a && source $appRootDir/config/.env && set +a && yarn --cwd $backstageDir dev
-	yarn --cwd $backstageDir dev
+	set -a && source $appRootDir/config/.env && set +a && yarn --cwd $backstageDir dev
+	# yarn --cwd $backstageDir dev
 	echo "Local dev startup completed"
 }
 
 start_local_debug(){  ## Start the backstage app for local development with debugging enabled
 	echo "Starting a local PostgreSQL container"
 	docker compose -f $appRootDir/config/docker-compose.yml up --build --detach
 	echo "Starting the backstage app with debug"
-	# set -a && source $appRootDir/config/.env && set +a && yarn --cwd ./backstage dev-debug
+	set -a && source $appRootDir/config/.env && set +a && yarn --cwd ./backstage dev-debug
 	$backstageDir/node_modules/.bin/concurrently "yarn --cwd $backstageDir start" "yarn --cwd $backstageDir start-backend --inspect"
 	echo "Local dev startup completed"
 }

diff --git a/website/docs/faq.md b/website/docs/faq.md
@@ -106,7 +106,7 @@ toc_max_heading_level: 4
 > OPA on AWS aims to provide a productive, efficient, and delightful developer experience by providing a simplified way to use AWS. By nature, the AWS console will enable the skilled cloud engineer to fine-tune and define their needs, however, OPA on AWS will enable a persona to build on AWS without having to know how to operate all the knobs and dials.
 <br/>
 
-#### What is an Internal Developing Platform (IDP)?
+#### What is an Internal Development Platform (IDP)?
 > 
 > Please refer to [platformengineering.org](https://platformengineering.org/blog/internal-developer-platforms-from-idea-to-reality)
 <br/>

diff --git a/website/docs/techdocs/customizations.md b/website/docs/techdocs/customizations.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 7
+title: Customizations
+
+---
+
+# Customizing and Extending OPA on AWS
+
+## Running locally
+
+It is possible to run the OPA UI and Backstage database locally on your workstation via a container runtime such as Docker Desktop. Running locally makes it much faster to customize OPA and see your changes running quickly. Other benefits include restarting or "bouncing" OPA/Backstage easily and clearing out the Backstage database (running on a local container) and starting fresh, without impacting others.
+
+To run the OPA UI and Backstage database locally, use this command:
+
+`make start-local`
+
+This command will spin up container images for a local PostgreSQL database and let you view the OPA UI via localhost (e.g. http://localhost:3000).
+
+NOTE: You need to have run `make install` at least once successfully before the `make start-local` command can be run.
+
+## How to modify OPA plugins
+
+If you want to modify any OPA plugins and see the effects of your changes locally, you'll need to do the following:
+
+  1. Update the `build-script/backstage-install.sh` file and change the value of the `installMode` variable from `npm` to `from-source`. This will make it so that building OPA UI/Backstage will use the plugin code from your local project instead of downloading official OPA plugins from the NPM registry.
+  2. After each change to plugins code, you will need rebuild the plugins and restart your locally-running Backstage instance before you can see the changes show up on your locally running Backstage. To rebuild the plugins, execute `make backstage-install`. To start or restart Backstage, execute `make start-local`
+
+## How to add or modify software templates
+
+If you want to modify existing OPA (app/resource/environment) templates and test them locally, do the following:
+
+  1. Make your template changes
+  2. Run this command to deploy your templates so that Backstage will use your latest version when scaffolding:  
+     `make push-backstage-reference-repo`.
+
+You can add your own software templates as well. To do this, you need to let Backstage know about your template so that it can show it in its UI. 
+
+Out of the box, OPA defines what templates to use in a file at `backstage-reference/templates/all-templates.yaml`. You can add a reference to your new template in this file.
+
+The below code snippet shows where the `all-templates.yaml` file is referred to from Backstage configurations file at `config/app-config.aws-production.yaml`
+
+```
+catalog:
+
+  locations:
+    # AWS templates
+    - type: url
+      target: https://${SSM_GITLAB_HOSTNAME}/opa-admin/backstage-reference/-/blob/main/templates/all-templates.yaml
+      rules:
+        - allow: [Location, Template]
+```