dan/per-10200-write-docs-on-how-to-use-opal (#612)

* Added OPAL+ docs * Fixed invalid links * Changed OPAL+ docs * Added OPAL+ features * Added OPAL+ support * Added troubleshooting docs * Fixed pre-commit * Fixed broken link * Added OPAL+ custom data fetcher providers feature
permitio · Jul 16, 2024 · e5f5dba · e5f5dba
1 parent 3801481
commit e5f5dba
Show file tree

Hide file tree

Showing 6 changed files with 177 additions and 13 deletions.
diff --git a/documentation/docs/opal-plus/deploy.mdx b/documentation/docs/opal-plus/deploy.mdx
@@ -0,0 +1,34 @@
+---
+sidebar_position: 2
+title: Deploy OPAL+
+---
+
+With OPAL+, you get access to private Docker images that include additional features and capabilities.
+To apply for Permit OPAL+, [fill in the form available here](https://hello.permit.io/opal-plus)
+
+In order to access the OPAL+ Docker images, you need to have Docker Hub credentials with an access token.
+Those should be received from your Customer Success manager.
+Reach out to us [on Slack](https://bit.ly/permit-slack) if you need assistance.
+
+## Accessing the OPAL+ Docker Images
+
+To access the OPAL+ Docker images, you need to log in to Docker Hub with your credentials.
+You can do this by running the [docker login](https://docs.docker.com/reference/cli/docker/login/) command:
+
+```bash
+docker login -u <username> -p <password>
+```
+
+If you are using Kubernetes, check out the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) on how to pull images from a private registry.
+
+After logging in, you can pull the OPAL+ Docker images using the following commands:
+
+```bash
+docker pull permitio/opal-plus:latest
+```
+
+## Running the OPAL+ Docker Images
+
+Running the OPAL+ Docker images is similar to running the open-source OPAL images.
+
+Check out the [OPAL Docker documentation](/getting-started/running-opal/run-docker-containers) for more information.
diff --git a/documentation/docs/opal-plus/features.mdx b/documentation/docs/opal-plus/features.mdx
@@ -0,0 +1,80 @@
+---
+sidebar_position: 3
+title: Advanced Features
+---
+
+OPAL+ has a number of advanced features extending the capabilities of the open-source OPAL.
+These features are available to OPAL+ users only.
+
+To apply for Permit OPAL+, [fill in the form available here](https://hello.permit.io/opal-plus)
+
+
+## Support and SLA
+
+OPAL+ provides dedicated support and a custom SLA to help you get the most out of your OPAL+ deployment.
+Reach out to us [on Slack](https://bit.ly/permit-slack) for more information.
+
+## Licensing Capabilities
+
+OPAL+ provides additional licensing capabilities to help you manage your OPAL+ deployment.
+Reach out to us [on Slack](https://bit.ly/permit-slack) for more information.
+
+## Custom Data Fetcher Providers
+
+OPAL+ provides custom data fetcher providers to help you fetch data from your private data sources.
+
+## Logging and Monitoring
+
+OPAL+ provides advanced logging and monitoring capabilities to help you track and debug your OPAL+ deployment.
+
+#### Connect to logging system
+
+On production, we advise you to connect OPAL+ to your logging system to collect and store the logs.
+Configure the [OPAL_LOG_SERIALIZE](/getting-started/configuration) environment variable to `true` to serialize logs in JSON format.
+
+#### Monitor OPAL Servers and Clients
+
+OPAL+ provides monitoring endpoints to help you track the health of your OPAL+ servers and clients.
+Configure the [OPAL_STATISTICS_ENABLED=true](/getting-started/configuration) environment variable to enable the statistics APIs.
+
+You can then monitor the state of your OPAL+ cluster by calling the `/stats` API route on the server.
+```bash
+curl http://opal-server:8181/stats -H "Authorization: Bearer <token>"
+# { "uptime": "2024-07-14T14:55:02.710Z", "version": "0.7.8", "client_count": 1, "server_count": 1 }
+```
+
+You can also get detailed information about the OPAL+ clients and servers by calling the `/statistics` API route on the server.
+```bash
+curl http://opal-server:8181/statistics -H "Authorization: Bear <token>"
+```
+```json
+{
+  "uptime": "2024-07-14T14:54:09.809Z",
+  "version": "0.7.8",
+  "clients": {
+    "opal-client-1": [
+      {
+        "rpc_id": "7ba198b1329d439faaa79dd7447401dc",
+        "client_id": "693ac1b4d060416eaad50c2bf04121b1",
+        "topics": [
+          "string"
+        ]
+      }
+    ],
+    "opal-client-2": [
+      {
+        "rpc_id": "d343d92292794630994a8a077bcb413a",
+        "client_id": "4d71d88ba16f49e1a0ae89f16c5a55d5",
+        "topics": [
+          "string"
+        ]
+      }
+    ]
+  },
+  "servers": [
+    "774b376fbead49b79f6a9fd42cef2cfd"
+  ]
+}
+```
+
+For more information on monitoring OPAL, see the [Monitoring OPAL](/tutorials/monitoring_opal) tutorial.
diff --git a/documentation/docs/OPAL_PLUS.mdx → ...mentation/docs/opal-plus/introduction.mdx b/documentation/docs/OPAL_PLUS.mdx → ...mentation/docs/opal-plus/introduction.mdx
@@ -1,8 +1,9 @@
 ---
 sidebar_position: 1
-title: Permit OPAL+ (Extended OPAL License)
+title: Introduction
 ---
 
+
 <div
   style={{
     display: "flex",
@@ -34,13 +35,13 @@ The package can include:
 - Dedicated support channel
 - Custom SLA
 - Professional services for OPAL
-- [Custom data-fetcher providers](tutorials/write_your_own_fetch_provider), including NRE.
+- [Custom data-fetcher providers](/tutorials/write_your_own_fetch_provider), including NRE.
 
-## Who Can Get Access to OPAL+
+See more about the [features of OPAL+](/opal-plus/features).
 
-The OPAL+ program is available for select enterprises, who apply for access;
-Currently the program can accept up to 5 enterprises. Applications are reviewed and considered on a first come first served basis.
+## Joining the OPAL+ Program
 
-## How to Apply to OPAL+
+The OPAL+ program is available for select enterprises, who apply for access;
+Currently the program can accept up to 5 enterprises. Applications are reviewed and considered on a first-come-first-served basis.
 
 To apply for Permit OPAL+, [fill in the form available here](https://hello.permit.io/opal-plus)
diff --git a/documentation/docs/opal-plus/troubleshooting.mdx b/documentation/docs/opal-plus/troubleshooting.mdx
@@ -0,0 +1,43 @@
+---
+sidebar_position: 10
+title: Troubleshooting
+---
+
+When something goes wrong, we are here to help.
+
+Feel free to reach out to us on Slack on our [community channel](https://bit.ly/opal-slack)
+or in your dedicated OPAL+ support channel, and we will do our best to assist you quickly.
+
+### Seeking Support
+
+When seeking support, please provide as much information as possible to help us understand the issue and resolve it faster.
+This includes:
+* Full description of the problem
+* Steps to reproduce the issue
+* Environment details (OS, Docker, Kubernetes, etc.)
+
+You can also provide the following information:
+
+#### Extract Logs
+
+On production, we advise you to connect OPAL+ to your logging system to collect logs.
+Configure the [OPAL_LOG_SERIALIZE](/getting-started/configuration) environment variable to `true` to serialize logs in JSON format.
+
+When running OPAL+ locally or in a development environment, you can extract logs from the console.
+Alternatively, you can enable logging to file by setting the [OPAL_LOG_TO_FILE](/getting-started/configuration) to `true`.
+
+You can also enable debug logs by setting the [OPAL_LOG_LEVEL](/getting-started/configuration) environment variable to `debug`.
+
+#### Export Configuration
+
+You can export your configuration by running the following command:
+
+```bash
+opal-client print-config
+```
+
+Make sure to censor any sensitive information, like passwords or API keys, before sharing the configuration.
+
+## Common Issues
+
+More common issues and their solutions are available in the [OPAL documentation](/getting-started/running-opal/troubleshooting).
diff --git a/documentation/docs/release-updates.mdx b/documentation/docs/release-updates.mdx
@@ -20,7 +20,7 @@ us and asking for additional capabilities on top of those provided by OPAL.
 
 If you just need a hosted version of OPAL; or you're building application-level permissions consider simply using [Permit.io's PRO tier](https://www.permit.io/pricing).
 
-Read more about **[OPAL+ here](/OPAL_PLUS)**.
+Read more about **[OPAL+ here](/opal-plus/introduction)**.
 :::
 
 ---
@@ -65,7 +65,7 @@ request is an 401, no secret was provided. This is unexpected as the configurati
 4.  Bump `http-cache-semantics` from `4.1.0` to `4.1.1` in `/documentation`
 5.  Bump `eta`, `@docusaurus/core` and `@docusaurus/preset-classic` in `/documentation`
 6.  Bump `@sideway/formula` from `3.0.0` to `3.0.1` in `/documentation`
-7.  Addition of **[OPAL-plus](/OPAL_PLUS)**
+7.  Addition of **[OPAL-plus](/opal-plus/introduction)**
 
 ---
 

diff --git a/documentation/sidebars.js b/documentation/sidebars.js
@@ -283,14 +283,20 @@ const sidebars = {
       label: "Fetch Providers",
     },
     {
-      type: "doc",
-      id: "FAQ",
-      label: "FAQ",
+      type: "category",
+      label: "💎 OPAL+ (Extended License)",
+      collapsed: true,
+      items: [
+        {
+          type: "autogenerated",
+          dirName: "opal-plus",
+        },
+      ],
     },
     {
       type: "doc",
-      id: "OPAL_PLUS",
-      label: "OPAL + (Extended OPAL License)",
+      id: "FAQ",
+      label: "FAQ",
     },
   ],
 };