From aa5f2b8f9fc756d86c3577d3b13466dc48a613b1 Mon Sep 17 00:00:00 2001 From: Anthony Watson Date: Tue, 2 Apr 2024 12:22:06 -0700 Subject: [PATCH] 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 Co-authored-by: Jim McVea --- .../package.json | 3 +- build-script/local-runners.sh | 6 +-- website/docs/faq.md | 2 +- website/docs/techdocs/customizations.md | 51 +++++++++++++++++++ 4 files changed, 57 insertions(+), 5 deletions(-) create mode 100644 website/docs/techdocs/customizations.md diff --git a/backstage-plugins/plugins/scaffolder-backend-module-aws-apps/package.json b/backstage-plugins/plugins/scaffolder-backend-module-aws-apps/package.json index 84357091..4024e1f4 100644 --- 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 index 45e7d48c..faafea17 100755 --- a/build-script/local-runners.sh +++ b/build-script/local-runners.sh @@ -9,8 +9,8 @@ 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" } @@ -18,7 +18,7 @@ start_local_debug(){ ## Start the backstage app for local development with debu 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 index 88057bb4..9947151b 100644 --- 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.
-#### 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)
diff --git a/website/docs/techdocs/customizations.md b/website/docs/techdocs/customizations.md new file mode 100644 index 00000000..66d8b878 --- /dev/null +++ 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] +```