Additional Docs (#212)

* more docing

---------

Signed-off-by: Peter Macdonald <[email protected]>

README.md

@@ -19,11 +19,11 @@ This repository contains a collection of plugins for [Backstage](https://backsta
 
 ## Policies
 
-- [backstage-opa-policies](https://github.com/Parsifal-M/backstage-opa-policies#hello) - A collection of policies that can be used with the plugins in this repository.
+- [backstage-opa-policies](https://github.com/Parsifal-M/backstage-opa-policies#hello) - A collection of policies that can be used with the plugins in this repository. (WIP)
 
 ## Additional Documentation
 
-You can find some additional documentation including an architecture overview in the [docs](./docs) folder.
+Each Plugin has its own documentation in the [Plugins](./plugins/) Folder, I am however, slowly moving things to [Github pages](https://parsifal-m.github.io/backstage-opa-plugins/#/). Feel free to help out!
 
 ## Local Development
 

docs/README.md

@@ -4,18 +4,18 @@ This repository contains a collection of plugins for [Backstage](https://backsta
 
 ## Plugins
 
-- [backstage-opa-backend](./plugins/backstage-opa-backend/README.md) - A Backend Plugin that the [backstage-opa-entity-checker](./plugins/backstage-opa-entity-checker/README.md) consumes to evaluate policies.
+- [backstage-opa-backend](../plugins/backstage-opa-backend/README.md) - A Backend Plugin that the [backstage-opa-entity-checker](./plugins/backstage-opa-entity-checker/README.md) consumes to evaluate policies.
 - [plugin-permission-backend-module-opa-wrapper](/opa-permissions-wrapper-module/introduction.md) - An isolated OPA Client and a Policy Evaluator that integrates with the Backstage permissions framework and uses OPA to evaluate policies, making it possible to use OPA for permissions (like RBAC).
-- [backstage-opa-entity-checker](./plugins/backstage-opa-entity-checker/README.md) - A frontend plugin that provides a component card that displays if an entity has the expected entity metadata according to an opa policy.
-- [backstage-opa-policies](./plugins/backstage-opa-policies/README.md) - A frontend component designed to be added to entity pages to fetch and display the OPA policy that entity uses based on a URL provided in an annotation in the `catalog-info.yaml` file.
+- [backstage-opa-entity-checker](../plugins/backstage-opa-entity-checker/README.md) - A frontend plugin that provides a component card that displays if an entity has the expected entity metadata according to an opa policy.
+- [backstage-opa-policies](../plugins/backstage-opa-policies/README.md) - A frontend component designed to be added to entity pages to fetch and display the OPA policy that entity uses based on a URL provided in an annotation in the `catalog-info.yaml` file.
 
 ## Policies
 
 - [backstage-opa-policies](https://github.com/Parsifal-M/backstage-opa-policies#hello) - A collection of policies that can be used with the plugins in this repository. (WIP)
 
 ## Additional Documentation
 
-You can find some additional documentation including an architecture overview in the [docs](./docs) folder.
+Each plugin also has its own documentation in the README file in the plugin folder.
 
 ## Local Development
 

docs/_sidebar.md

@@ -1,9 +1,19 @@
 - [Home](/)
-- [OPA Permissions Wrapper Module](/opa-permissions-wrapper-module/introduction.md)
-  - [Introduction](/opa-permissions-wrapper-module/introduction.md)
-  - [Quick Start](/opa-permissions-wrapper-module/quick-start.md)
-  - [Local Development](/opa-permissions-wrapper-module/local-development.md)
-  - [Example Inputs and Outputs](/opa-permissions-wrapper-module/inputs-and-outputs.md)
-  - [Architecture](/opa-permissions-wrapper-module/architecture.md)
-- [Contributing](/CONTRIBUTING.md)
-- [Adopters](/ADOPTERS.md)
+- [OPA Permissions Wrapper Module](opa-permissions-wrapper-module/introduction.md)
+  - [Quick Start](opa-permissions-wrapper-module/quick-start.md)
+  - [Example Permissions (RBAC) Policy](opa-permissions-wrapper-module/example-rbac-policy.md)
+  - [Catalog Rules](opa-permissions-wrapper-module/catalog-rules.md)
+  - [Scaffolder Rules](opa-permissions-wrapper-module/scaffolder-rules.md)
+  - [Local Development](opa-permissions-wrapper-module/local-development.md)
+  - [Example Inputs and Outputs](opa-permissions-wrapper-module/inputs-and-outputs.md)
+  - [Architecture](opa-permissions-wrapper-module/architecture.md)
+- [OPA Backend](opa-backend/introduction.md)
+  - [Quick Start](opa-backend/quick-start.md)
+- [OPA Entity Checker](opa-entity-checker/introduction.md)
+  - [Quick Start](opa-entity-checker/quick-start.md)
+  - [Local Development](opa-entity-checker/local-development.md)
+  - [Example Entity Checker Policy](opa-entity-checker/example-entity-checker-policy.md)
+- [OPA Policies](opa-policies/introduction.md)
+  - [Quick Start](opa-policies/quick-start.md)
+- [Contributing](CONTRIBUTING.md)
+- [Adopters](ADOPTERS.md)

docs/index.html

@@ -7,8 +7,12 @@
       name="viewport"
       content="width=device-width, initial-scale=1, minimum-scale=1.0, shrink-to-fit=no, viewport-fit=cover"
     />
-    <meta name="description" content="" />
-    <title></title>
+    <meta name="description" content="OPA Plugins for Backstage." />
+    <meta
+      name="keywords"
+      content="OPA, Backstage, Permissions, Security, Policy Management, Open Policy Agent"
+    />
+    <title>Backstage OPA Plugins Documentation</title>
 
     <!-- Theme: Simple (light + dark) -->
     <link
@@ -21,24 +25,22 @@
       media="(prefers-color-scheme: dark)"
       href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"
     />
-
-    <!-- Custom Styles -->
-    <style>
-      :root {
-        /* --theme-hue: 325; */
-      }
-    </style>
+    <!-- Favicon -->
+    <link rel="icon" href="path/to/your/favicon.ico" type="../img/logo.png" />
   </head>
 
   <body>
     <div id="app"></div>
     <!--Edit on Github-->
     <script src="//cdn.jsdelivr.net/npm/docsify-edit-on-github"></script>
-    <script src="//unpkg.com/[email protected]/dist/docsify-mermaid.js"></script>
     <script>
       // Docsify Configuration
       window.$docsify = {
         loadSidebar: true,
+        alias: {
+          '/.*/_sidebar.md': '/_sidebar.md',
+        },
+        sidebarDisplayLevel: 1, // set sidebar display level
         plugins: [
           EditOnGithubPlugin.create(
             'https://github.com/Parsifal-M/backstage-opa-plugins/tree/main/docs',
@@ -54,6 +56,7 @@
     <!-- Recommended -->
     <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>
     <!--Copy To Clipboard-->
     <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
     <!--Mermaid-->

docs/opa-backend/introduction.md

@@ -0,0 +1,19 @@
+![NPM Version](https://img.shields.io/npm/v/%40parsifal-m%2Fplugin-opa-backend?logo=npm) ![NPM Downloads](https://img.shields.io/npm/dw/%40parsifal-m%2Fplugin-opa-backend)
+
+# backstage-opa-backend
+
+A backend plugin for Backstage, this plugin integrates with the Open Policy Agent (OPA) to facilitate policy evaluation. It's designed to work with the frontend plugins [OPA Entity Checker](../opa-entity-checker/introduction.md) and [OPA Policies](../opa-policies/introduction.md). By itself, this plugin does not provide any user-facing features.
+
+> Note: This plugin is **NOT** required for the [OPA Permissions Wrapper Module](../opa-permissions-wrapper-module/introduction.md).
+
+To quickly get started with this plugin, follow the steps below.
+
+- [Quick-start Guide](./quick-start.md)
+
+## Contributing
+
+Contributions are welcome! If you're interested in enhancing this plugin, please fork the repository and submit a PR with your changes. For any questions or discussions, feel free to reach out on [Mastodon](https://hachyderm.io/@parcifal).
+
+## License
+
+Licensed under the Apache 2.0 License.

docs/opa-backend/quick-start.md

@@ -0,0 +1,69 @@
+# Quick Start
+
+This guide will help you get started with the OPA Backend module for Backstage.
+
+## Pre-requisites
+
+- You have deployed OPA, kindly see how to do that [here](https://www.openpolicyagent.org/docs/latest/deployments/), or see below.
+
+## Deploying OPA
+
+There are many ways to deploy OPA, and there is no one size fits all. A good way is to deploy OPA as a sidecar to your Backstage instance. This way, you can ensure that OPA is always available when your Backstage instance is running.
+
+Here is an example of how you could update your Backstage `k8s` deployment to include OPA, this would be an extension of the `k8s` deployment that you are using for your Backstage instance.
+
+```yaml
+#... Backstage deployment configuration with OPA
+spec:
+  containers:
+    - name: backstage
+      image: your-backstage-image
+      ports:
+        - name: http
+          containerPort: 7007
+    - name: opa
+      image: openpolicyagent/opa:0.65.0 # Pin a version of your choice
+      ports:
+        - name: http
+          containerPort: 8181
+      args:
+        - 'run'
+        - '--server'
+        - '--log-format=json-pretty'
+        - '--set=decision_logs.console=true'
+        - '--ignore=.*'
+        - '--watch' # Watch for policy changes, this allows updating the policy without restarting OPA
+        - '/policies'
+      volumeMounts:
+        - readOnly: true
+          name: opa-policy
+          mountPath: /policies
+  volumes:
+    - name: opa-policy
+      configMap:
+        name: opa-policy
+```
+
+## Installing The OPA Backend Plugin
+
+Run the following command to install the OPA Backend Plugin in your Backstage project.
+
+```bash
+yarn add --cwd packages/backend @parsifal-m/plugin-opa-backend
+```
+
+Then make the following changes to the `packages/backend/src/index.ts` file in your Backstage project.
+
+```diff
+import { createBackend } from '@backstage/backend-defaults';
+
+const backend = createBackend();
+backend.add(import('@backstage/plugin-app-backend/alpha'));
+backend.add(import('@backstage/plugin-auth-backend'));
+// ..... other plugins
++ backend.add(import('@parsifal-m/plugin-opa-backend'));
+```
+
+## Recommendations
+
+I recommend using [Regal: A linter and language server for Rego](https://github.com/StyraInc/regal) to help you write your policies. It provides syntax highlighting, linting, and type checking for Rego files.

example-opa-policies/entity_checker.rego → docs/opa-entity-checker/example-entity-checker-policy.md

@@ -1,3 +1,8 @@
+# Example Entity Checker Policy
+
+This is an example policy for the OPA Entity Checker plugin. This policy is used to check if an entity has the correct metadata set. This could be used as a starting point for your own policies.
+
+```rego
 package entity_checker
 
 import rego.v1
@@ -45,3 +50,4 @@ violation contains {"check_title": entity_check, "message": msg, "level": "error
 	entity_check := "Type"
 	msg := "Incorrect component type!"
 }
+```

docs/opa-entity-checker/introduction.md

@@ -0,0 +1,40 @@
+![NPM Version](https://img.shields.io/npm/v/%40parsifal-m%2Fplugin-opa-entity-checker?logo=npm) ![NPM Downloads](https://img.shields.io/npm/dw/%40parsifal-m%2Fplugin-opa-entity-checker)
+
+# Keep Your Entity Data In Check With OPA Entity Checker
+
+Welcome to a smarter way to ensure data quality! The opa-entity-checker plugin, powered by [OPA](https://github.com/open-policy-agent/opa), offers a straightforward solution to validate your entities against custom policies. It's a great tool for maintaining high data standards in your Backstage instance. And keeps teams on their toes to ensure data quality is always good.
+
+## How It Works
+
+With opa-entity-checker, you can automatically verify if your entities comply with the policies you've set. It displays a clear, concise card on the entity page, indicating the compliance status:
+
+- **Compliant Entities:** A clean card signifies everything is in order.
+
+  ![MetaData Card No Violations](../assets/card2.png)
+
+- **Non-Compliant Entities:** A detailed card highlights what needs attention.
+
+  ![MetaData Card Violations](../assets/card1.png)
+
+For more details, check out:
+
+- [Quick-start Guide](/opa-entity-checker/quick-start.md)
+- [Local Development Guide](/opa-entity-checker/local-development.md)
+
+## Community
+
+This project is part of the Backstage and Open Policy Agent communities. For more information, please visit:
+
+- [Backstage](https://backstage.io)
+- [Open Policy Agent](https://www.openpolicyagent.org)
+- [Styra](https://www.styra.com)
+- [OPA Slack](https://slack.openpolicyagent.org/)
+- [Backstage Discord](https://discord.com/invite/MUpMjP2)
+
+## Get Involved
+
+Your contributions can make opa-entity-checker even better. Fork the repository, make your changes, and submit a PR. If you have questions or ideas, reach out on [Mastodon](https://hachyderm.io/@parcifal).
+
+## License
+
+This project is licensed under the Apache 2.0 License.