### Multi-Topic Architecture Example

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Illustrates the traditional OPAL setup where each tenant requires its own data topic, necessitating service restarts when adding new tenants.

```bash
Tenant 1: OPAL_DATA_TOPICS=tenant_1_data  

Tenant 2: OPAL_DATA_TOPICS=tenant_1_data,tenant_2_data  # requires restart  

Tenant 3: OPAL_DATA_TOPICS=tenant_1_data,tenant_2_data,tenant_3_data  # requires restart  
```

--------------------------------

### Download and Run Example Docker Compose

Source: https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks

Use this command to download and run a pre-configured docker-compose setup for OPAL with callbacks and healthcheck policy enabled.

```bash
curl -L https://raw.githubusercontent.com/permitio/opal/master/docker/docker-compose-with-callbacks.yml \
> docker-compose.yml && docker-compose up
```

--------------------------------

### Download and Run OPAL Docker Compose

Source: https://docs.opal.ac/getting-started/quickstart/opal-playground/run-server-and-client

Use this command to download the example docker-compose.yml file and start the OPAL server and client containers.

```bash
curl -L https://raw.githubusercontent.com/permitio/opal/master/docker/docker-compose-example.yml \
> docker-compose.yml && docker-compose up
```

--------------------------------

### Clone and Run Cedar-Agent Example

Source: https://docs.opal.ac/tutorials/cedar

Clone the OPAL repository and launch the example configuration with Docker Compose to get Cedar-Agent running.

```bash
git clone https://github.com/permitio/opal.git  

cd opal  

docker compose -f docker/docker-compose-example-cedar.yml up -d  
```

--------------------------------

### Docker Compose Example for Custom Fetch Provider

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

This example shows a docker-compose setup for using a custom fetch provider. It includes configuring the OPAL client with the custom provider module and setting up the OPAL server with a DataSourceEntry that utilizes the custom fetcher.

```yaml
version: "3.7"
services:
  opal-client:
    build:
      context: ./opal-client
    environment:
      - OPAL_FETCH_PROVIDER_MODULES=opal_fetcher_postgres.provider
      - OPAL_DATA_CONFIG_SOURCES={"config": {"entries": [{"url": "postgresql://postgres@example_db:5432/postgres", "config": {"fetcher": "PostgresFetchProvider", "query": "SELECT * from city;", "connection_params": {"password": "postgres"}}, "topics": ["policy_data"], "dst_path": "cities"}]}}
    depends_on:
      - opal-server

  opal-server:
    image: "ghcr.io/open-policy-agent/opal:v0.10.0"
    ports:
      - "8080:8080"
    volumes:
      - ./policy-data:/policy-data
    environment:
      - OPAL_POLICY_TOPICS=policy_data
      - OPAL_POLICY_TOPICS_DIRS=/policy-data

  example_db:
    image: postgres:13
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    ports:
      - "5432:5432"
```

--------------------------------

### Start Services

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Starts the OPAL and OPA services using Docker Compose. Ensure you are in the project root directory.

```bash
docker compose -f docker/docker-compose-single-topic-multi-tenant.yml up -d
```

--------------------------------

### Run Docker Compose Example with Proxy

Source: https://docs.opal.ac/tutorials/setup_opal_behind_proxy

Use this command to start the OPAL server and client with a Squid proxy. It demonstrates configuring proxy environment variables for HTTP traffic while maintaining direct network connectivity.

```bash
docker compose -f docker/docker-compose-with-proxy-example.yml up
```

--------------------------------

### Install opal-client CLI

Source: https://docs.opal.ac/getting-started/quickstart/opal-playground/publishing-data-update

These commands set up a Python virtual environment and install the opal-client CLI, which is necessary for publishing data updates.

```shell
pyenv virtualenv opaldemo

pyenv activate opaldemo

pip install opal-client
```

--------------------------------

### Install opal-client Package

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/opal-client-setup

Install the opal-client Python package using pip.

```bash
pip install opal-client  
```

--------------------------------

### Install opal-client CLI

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-client/obtain-jwt-token

Installs the `opal-client` command-line interface tool. This is a prerequisite for using the CLI to obtain a JWT token.

```bash
# this command is not necessary if you already created this virtualenv
pyenv virtualenv opal

# this command is not necessary if the virtualenv is already active
pyenv activate opal

# this command installs the client cli
pip install opal-client

```

--------------------------------

### Run OPAL Server with Gunicorn and Backbone Pub/Sub

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/running-in-prod

Combine Gunicorn and a backbone pub/sub configuration (Postgres example) for a full production setup of the OPAL server.

```bash
OPAL_BROADCAST_URI=postgres://localhost/mydb opal-server run --engine-type gunicorn
```

--------------------------------

### Install permit-broadcaster with Pulsar support

Source: https://docs.opal.ac/tutorials/run_opal_with_pulsar

Install the necessary module to enable Apache Pulsar as a backbone for OPAL-server.

```bash
pip install permit-broadcaster[pulsar]
```

--------------------------------

### Install Broadcaster with Kafka Support

Source: https://docs.opal.ac/tutorials/run_opal_with_kafka

Install the broadcaster package with Kafka support. Note: Starting with OPAL 0.1.21, this is included with OPAL.

```bash
pip install broadcaster[kafka]
```

--------------------------------

### Install OPAL Client Package

Source: https://docs.opal.ac/tutorials/install_as_python_packages

Installs the OPAL client package using pip. Ensure Python 3.7 or greater is installed.

```bash
pip install opal-client
```

--------------------------------

### Run the OPAL Client

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/opal-client-setup

Start the OPAL client. Configuration can be done via environment variables or command-line options.

```bash
opal-client run  
```

--------------------------------

### OPAL Server Log Output Example (Tenant 2)

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Example log output from the OPAL server when processing the configuration for tenant2. It mirrors the process for tenant1.

```text
Publishing data update to topics: {'tenant_data'}, reason: Add tenant2 data source, entries: [{'url': 'http://example_external_data_provider:80/acl/tenant2', 'method': 'PUT', 'path': '/acl/tenant2', 'inline_data': False, 'topics': ['tenant_data']}]  
185.199.109.133:59019 - "POST /data/config HTTP/1.1" 200  
Broadcasting incoming event: {'topic': 'tenant_data', 'notifier_id': '4dd064469d75485c9d3547c7dda55215'}  
```

--------------------------------

### Configure OPAL Server with Backbone Pub/Sub (Postgres Example)

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/running-in-prod

Configure the OPAL server to use a backbone pub/sub system by setting the `OPAL_BROADCAST_URI` environment variable. This example uses Postgres.

```bash
OPAL_BROADCAST_URI=postgres://localhost/mydb opal-server run
```

--------------------------------

### Install OPAL Server Package

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/opal-server-setup

Installs the OPAL server using pip. This command makes the `opal-server` executable available.

```bash
pip install opal-server
```

--------------------------------

### OPAL Server Log Output Example (Tenant 1)

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Example log output from the OPAL server when processing the configuration for tenant1. It shows the data update being published.

```text
Publishing data update to topics: {'tenant_data'}, reason: Add tenant1 data source, entries: [{'url': 'http://example_external_data_provider:80/acl/tenant1', 'method': 'PUT', 'path': '/acl/tenant1', 'inline_data': False, 'topics': ['tenant_data']}]  
185.199.109.133:55981 - "POST /data/config HTTP/1.1" 200  
Broadcasting incoming event: {'topic': 'tenant_data', 'notifier_id': '7a4b55cd27d34df8a1e4ff5fc5c7516f'}  
```

--------------------------------

### Run Single-Topic Multi-Tenant Demo

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Execute this script to run the complete demo setup for a single-topic multi-tenant architecture. Ensure you are in the 'docker' directory before running.

```bash
cd docker  

./run-example-with-single-topic-multi-tenant.sh  
```

--------------------------------

### Example .manifest File Content

Source: https://docs.opal.ac/tutorials/track_a_git_repo

An example of the content for a .manifest file, specifying the order in which policy modules should be loaded by the OPAL client. Paths are relative to the .manifest file.

```text
utils.rego
rabc.rego
```

--------------------------------

### OPAL Client Log Output Example (Tenant 2)

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Example log output from the OPAL client for tenant2, similar to tenant1. It demonstrates the client's response to a new data update notification.

```text
Received notification of event: tenant_data  
Updating policy data, reason: Add tenant2 data source  
Triggering data update with id: 1f355993f9334f35b781232c591e65e5  
Fetching data from url: http://example_external_data_provider:80/acl/tenant2  
Saving fetched data to policy-store: source url='http://example_external_data_provider:80/acl/tenant2', destination path='/acl/tenant2'  
Received request.    PUT /v1/data/acl/tenant2  
Sent response.       PUT /v1/data/acl/tenant2 -> 204  
```

--------------------------------

### Install Latest OPAL Version

Source: https://docs.opal.ac/tutorials/helm-chart-for-kubernetes

Installs the latest stable version of OPAL into a dedicated namespace named 'opal-ns'. Creates the namespace if it doesn't exist.

```bash
helm install --create-namespace -n opal-ns opal permitio/opal
```

--------------------------------

### Install OPAL CLI

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-server/policy-repo-syncing

Install the OPAL CLI within a new Python virtual environment. This is a prerequisite for generating webhook secrets.

```bash
pyenv virtualenv opal
pyenv activate opal
pip install opal-server
```

--------------------------------

### OPAL Client Log Output Example (Tenant 1)

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Example log output from the OPAL client when it receives a notification for tenant1 and updates its policy data. It shows the fetch and save process.

```text
Received notification of event: tenant_data  
Updating policy data, reason: Add tenant1 data source  
Triggering data update with id: 51fc5aa4905e4f62a88be058b6572991  
Fetching data from url: http://example_external_data_provider:80/acl/tenant1  
Saving fetched data to policy-store: source url='http://example_external_data_provider:80/acl/tenant1', destination path='/acl/tenant1'  
Received request.    PUT /v1/data/acl/tenant1  
Sent response.       PUT /v1/data/acl/tenant1 -> 204  
```

--------------------------------

### Single-Topic Architecture Example

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Demonstrates the single-topic OPAL configuration where all tenants share a single topic, allowing for tenant addition without service restarts.

```bash
All tenants: OPAL_DATA_TOPICS=tenant_data  # no restart needed when adding tenants  
```

--------------------------------

### Get Opal Client Image with Built-in OPA

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-client/get-client-image

Use this command to pull the recommended Opal client image that includes OPA. This is suitable for most use cases, especially when OPA is not already installed.

```docker
docker pull permitio/opal-client
```

--------------------------------

### View OPAL Client Logs

Source: https://docs.opal.ac/tutorials/cedar

Check the logs for the OPAL client component when running the Docker Compose example.

```bash
docker compose -f docker/docker-compose-example-cedar.yml logs opal_client  
```

--------------------------------

### View OPAL Server Logs

Source: https://docs.opal.ac/tutorials/cedar

Check the logs for the OPAL server component when running the Docker Compose example.

```bash
docker compose -f docker/docker-compose-example-cedar.yml logs opal_server  
```

--------------------------------

### Install Specific OPAL Version

Source: https://docs.opal.ac/tutorials/helm-chart-for-kubernetes

Installs a specific version of OPAL using its version number. The namespace 'opal-ns' is created if it doesn't exist.

```bash
helm install --create-namespace -n opal-ns --version x.x.x opal permitio/opal
```

--------------------------------

### Run Docker Compose with Kafka

Source: https://docs.opal.ac/tutorials/run_opal_with_kafka

Use this command to launch the Docker Compose setup including OPAL-server, OPAL-client, Zookeeper, and Kafka.

```bash
docker compose -f docker/docker-compose-with-kafka-example.yml up --force-recreate
```

--------------------------------

### Migrate Complex Policy Example

Source: https://docs.opal.ac/tutorials/opa-version-migration

This example shows the migration of a more complex Rego policy, including changes to package declarations, assignments, and rule definitions.

```rego
package authz

import data.users

default allow = false

allow {
    user := data.users[input.user]
    user.role == "admin"
    input.action == "delete"
}

has_permission[user] {
    user := data.users[input.user]
    user.role == "admin"
}
```

```rego
package authz.v1

import data.users

default allow := false

allow if {
    user := data.users[input.user]
    user.role == "admin"
    input.action == "delete"
}

has_permission contains user if {
    user := data.users[input.user]
    user.role == "admin"
}
```

--------------------------------

### Install Specific OPAL Version with Custom Values

Source: https://docs.opal.ac/tutorials/helm-chart-for-kubernetes

Installs a specific version of OPAL using a custom configuration file ('myvalues.yaml'). The namespace 'opal-ns' is created if it doesn't exist.

```bash
helm install -f myvalues.yaml --create-namespace -n opal-ns --version x.x.x opal permitio/opal
```

--------------------------------

### Configure Data Source Configuration

Source: https://docs.opal.ac/getting-started/configuration

Define the configuration for data sources, specifying URLs and associated topics. This example configures a single source for the 'data' topic.

```json
{
  "config": {
    "entries": [
      {
        "url": "http://localhost:7002/policy-data",
        "topics": ["data"]
      }
    ]
  }
}
```

--------------------------------

### Run OPAL Client CLI

Source: https://docs.opal.ac/tutorials/install_as_python_packages

Provides commands to get help for the OPAL client CLI and to run the client as a daemon.

```bash
# get CLI help  
opal-client --help
```

```bash
# run the client as a daemon  
opal-client run
```

--------------------------------

### Install Package in Editable Mode

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Use `pip install -e` to install a package in editable mode, allowing direct use and modification of source code without building. This is useful for local development and testing of fetch providers.

```bash
pip install -e path/to/your/package

```

--------------------------------

### Kafka Event Data Example

Source: https://docs.opal.ac/tutorials/run_opal_with_kafka

This is an example of the data structure that appears in the Kafka topic when an event is broadcast.

```json
{"notifier_id": "9a9a97df1da64486a1a56a070f1c3db3", "topics": ["policy_data"], "data": {"id": null, "entries": [{"url": "https://api.country.is/23.54.6.78", "config": {}, "topics": ["policy_data"], "dst_path": "/users/bob/location", "save_method": "PUT"}]}, "reason": "", "callback": {"callbacks": []}}
```

--------------------------------

### Example Docker Run Command for OPAL

Source: https://docs.opal.ac/getting-started/running-opal/run-docker-containers

This command demonstrates how to run the OPAL server Docker container locally. It includes volume mounting for SSH, environment variables for authentication and policy repository URL, and port exposure.

```docker
docker run -it \
  -v ~/.ssh:/root/ssh \
  -e "OPAL_AUTH_PRIVATE_KEY=$(OPAL_AUTH_PRIVATE_KEY)" \
  -e "OPAL_AUTH_PUBLIC_KEY=$(OPAL_AUTH_PUBLIC_KEY)" \
  -e "OPAL_POLICY_REPO_URL=$(OPAL_POLICY_REPO_URL)" \
  -p 7002:7002 \
  permitio/opal-server
```

--------------------------------

### Start Docker Compose services

Source: https://docs.opal.ac/tutorials/run_opal_with_pulsar

Command to launch the services defined in the docker-compose.yml file. Use --force-recreate if you need to rebuild or restart existing containers.

```bash
docker compose up --force-recreate
```

--------------------------------

### Run OPAL Server with Gunicorn

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/running-in-prod

Use the `run` command with the `--engine-type gunicorn` option to start the OPAL server with Gunicorn for production. Consult `opal-server run --help` for more options.

```bash
opal-server run --engine-type gunicorn
```

--------------------------------

### Clone OPAL Repo and Run Docker Compose

Source: https://docs.opal.ac/getting-started/quickstart/opal-playground/run-server-and-client

Alternatively, clone the OPAL repository locally and use its example docker-compose file to run the server and client.

```bash
git clone https://github.com/permitio/opal.git

cd opal

docker compose -f docker/docker-compose-example.yml up
```

--------------------------------

### Run OPAL Server CLI

Source: https://docs.opal.ac/tutorials/install_as_python_packages

Provides commands to get help for the OPAL server CLI and to run the server as a daemon.

```bash
# get CLI help  
opal-server --help
```

```bash
# run server as daemon  
opal-server run
```

--------------------------------

### Example Server Data Source Configuration

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-server/data-sources

This JSON structure defines the data sources OPAL clients will fetch. It includes URLs, optional topics for client subscription, and configuration for fetching, such as HTTP headers.

```json
{
  "config": {
    "entries": [
      {
        "url": "https://api.permit.io/v1/policy-config",
        "topics": [
          ...
        ],
        "config": {
          "headers": {
            "Authorization": "Bearer FAKE-SECRET"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### Exclude Localhost from Proxy for Inline Setups

Source: https://docs.opal.ac/tutorials/setup_opal_behind_proxy

For inline OPA/Cedar setups, it is critical to exclude localhost and other local addresses from proxy routing by adding them to the NO_PROXY environment variable. This prevents OPAL Client requests to the local policy engine from failing.

```bash
NO_PROXY=localhost,127.0.0.1,::1,0.0.0.0  
```

--------------------------------

### Docker Compose configuration for OPAL-server and Pulsar

Source: https://docs.opal.ac/tutorials/run_opal_with_pulsar

Example docker-compose.yml to set up Apache Pulsar and OPAL-server. Ensure the OPAL_BROADCAST_URI is correctly set to the Pulsar service.

```yaml
version: '3'  

services:
  pulsar:
    image: apachepulsar/pulsar:3.3.1
    command: bin/pulsar standalone
    ports:
      - 6650:6650
      - 8080:8080
    volumes:
      - pulsardata:/pulsar/data
      - pulsarconf:/pulsar/conf
  
  opal-server:
    image: permitio/opal-server:latest
    environment:
      - OPAL_BROADCAST_URI=pulsar://pulsar:6650
    depends_on:
      - pulsar
  
volumes:
  pulsardata:
  pulsarconf:

```

--------------------------------

### Implement Fetch Provider's _fetch_ Method

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Implement the `_fetch_` method to retrieve data from a data source. Access the event URL and configuration via `self._event.url` and `self._event.config`. This example shows fetching data using an SQL query and returning records.

```python
async def _fetch_(self):

    self._event: PostgresFetchEvent # type casting

  

    # ...  

    # there was more code here, it's not very interesting for the tutorial ;)

    # ...  

  

    if self._event.config.fetch_one:

        row = await self._connection.fetchrow(self._event.config.query)

        return [row]

    else:

        return await self._connection.fetch(self._event.config.query)

```

--------------------------------

### OPAL Backbone Event JSON Schema Example

Source: https://docs.opal.ac/tutorials/run_opal_with_kafka

An example JSON object conforming to the OPAL backbone event schema, used for triggering events directly from Kafka.

```json
{"notifier_id": "9a9a97df1da64486a1a56a070f1c3db3", "topics": ["policy_data"], "data": {"id": null, "entries": [{"url": "https://api.country.is/23.54.6.78", "config": {}, "topics": ["policy_data"], "dst_path": "/users/bob/location", "save_method": "PUT"}], "reason": "User reconnected from new IP", "callback": {"callbacks": []}}}
```

--------------------------------

### Search for Available OPAL Versions

Source: https://docs.opal.ac/tutorials/helm-chart-for-kubernetes

Searches the added Helm repository for all available versions of the OPAL chart. Useful for identifying specific versions to install.

```bash
helm search repo opal --versions
```

--------------------------------

### Example Policy Update Message

Source: https://docs.opal.ac/tutorials/track_a_git_repo

An example of a policy update message sent by the OPAL server to its clients via pub/sub. This message includes the topic and the latest commit hash.

```json
{
  "topic": "policy:tenant2",
  "data": "5cdf36a7510f6ecc9e89cceb0ae0672c67ddb34c"
}
```

--------------------------------

### OPAL Client Request for Data Config

Source: https://docs.opal.ac/tutorials/configure_external_data_sources

An example of an OPAL client requesting its data configuration from the OPAL server.

```http
GET https://opal-server.com/data/config
```

--------------------------------

### Example OPAL_DATA_CONFIG_SOURCES with Custom Fetcher

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

This JSON structure demonstrates how to configure OPAL_DATA_CONFIG_SOURCES to use a custom fetch provider. The 'fetcher' key specifies the provider class name, and other keys like 'query' and 'connection_params' are specific to that provider.

```json
{
  "config": {
    "entries": [
      {
        "url": "postgresql://postgres@example_db:5432/postgres",
        "config": {
          "fetcher": "PostgresFetchProvider",
          "query": "SELECT * from city;",
          "connection_params": {
            "password": "postgres"
          }
        },
        "topics": ["policy_data"],
        "dst_path": "cities"
      }
    ]
  }
}
```

--------------------------------

### View opal-client Run Help

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/opal-client-setup

Display help for specific run option configurations for the opal-client.

```bash
opal-client run --help  
```

--------------------------------

### Opal Client Log Output During Data Update

Source: https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks

Example log output from the Opal client showing the process of receiving, updating, and reporting data updates.

```log
opal_client.data.rpc                    | INFO  | Received notification of event: policy_data

opal_client.data.updater                | INFO  | Updating policy data, reason:  

opal_client.data.updater                | INFO  | Triggering data update with id: c83b6862aa354d338d1a9e23794e3efc

opal_client.data.updater                | INFO  | Fetching policy data

opal_client.data.fetcher                | INFO  | Fetching data from url: https://api.country.is/23.54.6.78

opal_client.data.updater                | INFO  | Saving fetched data to policy-store: source url='https://api.country.is/23.54.6.78', destination path='/users/bob/location'

opal_client.policy_store.opa_client     | INFO  | processing store transaction: {'id': 'c83b6862aa354d338d1a9e23794e3efc', 'actions': ['set_policy_data'], 'success': True, 'error': ''}

opal_client.policy_store.opa_client     | INFO  | persisting health check policy: ready=true, healthy=true

opal_client.data.updater                | INFO  | Reporting the update to requested callbacks

opal_client.data.fetcher                | INFO  | Fetching data from url: http://opal_server:7002/data/callback_report
```

--------------------------------

### Run OPAL Client Container Locally

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-client/lets-run-the-client

Execute this command to run the OPAL client container locally, mapping necessary ports and passing the configured environment variables. This setup includes running OPA inline.

```bash
docker run -it \
  --env OPAL_CLIENT_TOKEN \
  --env OPAL_SERVER_URL \
  --env OPAL_DATA_TOPICS \
  -p 7766:7000 \
  -p 8181:8181 \
  permitio/opal-client 
```

--------------------------------

### Add OPAL Helm Repository

Source: https://docs.opal.ac/tutorials/helm-chart-for-kubernetes

Adds the OPAL Helm chart repository to your local Helm configuration. This is a prerequisite for installing the chart.

```bash
helm repo add permitio https://permitio.github.io/opal-helm-chart

helm repo update
```

--------------------------------

### Configure Default Disconnected Mode

Source: https://docs.opal.ac/tutorials/opal_server_connectivity

Set environment variables to start the OPAL client in disconnected mode by default. Ensure a valid backup file exists for offline operation.

```yaml
environment:
  - OPAL_OFFLINE_MODE_ENABLED=true
  - OPAL_DEFAULT_OPAL_SERVER_SERVER_CONNECTIVITY_DISABLED=true
volumes:
  - opa_backup:/opal/backup:rw
```

--------------------------------

### View opal-client Help

Source: https://docs.opal.ac/getting-started/running-opal/as-python-package/opal-client-setup

Display general commands and options for the opal-client.

```bash
opal-client --help  
```

--------------------------------

### Create External Scope with REST API

Source: https://docs.opal.ac/overview/scopes

This example demonstrates creating an 'external' scope, similar to the 'internal' scope, but configured to use policies from the 'external' directory of a Git repository.

```bash
curl --request PUT 'http://opal_server/scopes'  
--header 'Content-Type: application/json'  
--header 'Authorization: $OPAL_TOKEN'  
--data-raw '{  
  "scope_id": "external",  
  "policy": {  
    "source_type": "git",  
    "url": "https://github.com/company/policy",  
    "auth": {  
      "auth_type": "github_token",  
      "token": "github_token"  
    },  
    "directories": [  
      "external"  
    ],  
    "extensions": [  
      ".rego",  
      ".json"  
    ],  
    "manifest": ".manifest",  
    "poll_updates": true,  
    "branch": "main"  
  },  
  "data": {  
    "entries": []  
  }  
}'  
```

--------------------------------

### Dockerfile for Non-Published Python Package

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Create a custom Docker image for OPAL that includes your custom fetch provider when it's not published to PyPI. This Dockerfile inherits from the official OPAL-client image, copies your package source, and installs it.

```dockerfile
# inherits all behavior defined in the official OPAL-client image  

FROM permitio/opal-client:latest  

WORKDIR /app/  

# These two commands installs the python package from source  

COPY . ./  

RUN python setup.py install  
```

--------------------------------

### Opal Server Log Output During Data Update

Source: https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks

Example log output from the Opal server indicating a data update is being processed and published.

```log
opal_server.data.data_update_publisher  | INFO  | [10] Publishing data update to topics: ['policy_data'], reason: , entries: [('https://api.country.is/23.54.6.78', 'PUT', '/users/bob/location')]

uvicorn.protocols.http.httptools_impl   | INFO  | 172.27.0.1:63456 - "POST /data/config HTTP/1.1" 200

fastapi_websocket_pubsub.event_notifier | INFO  | calling subscription callbacks for sub_id=0d949d8473824c8280a3ff6ab9146cd0 with topic=policy_data

fastapi_websocket_pubsub.event_broadc...| INFO  | Broadcasting incoming event

fastapi_websocket_pubsub.event_notifier | INFO  | calling subscription callbacks for sub_id=ee10bc3da76444e899c58b861b0079c2 with topic=policy_data
```

--------------------------------

### Received Update Report by Callback Server

Source: https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks

Example log output from a server receiving an update report via a callback, confirming the data update's status.

```log
opal_server.data.api                    | INFO  | Received update report: {'update_id': 'c83b6862aa354d338d1a9e23794e3efc', 'reports': [{'entry': {'url': 'https://api.country.is/23.54.6.78', 'config': {}, 'topics': ['policy_data'], 'dst_path': '/users/bob/location', 'save_method': 'PUT'}, 'fetched': True, 'saved': True, 'hash': '3eb2f338beb6691bbeeeca60dc3f4afad74ec8c5881f8abe3aa23d57ffa48424'}]}

uvicorn.protocols.http.httptools_impl   | INFO  | 172.27.0.4:49720 - "POST /data/callback_report HTTP/1.1" 200
```

--------------------------------

### Pull the Opal Server Docker Image

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-server/get-server-image

Use this command to download the latest Opal server image from Docker Hub. Ensure Docker is installed on your machine.

```bash
docker pull permitio/opal-server
```

--------------------------------

### View CLI Help Options

Source: https://docs.opal.ac/getting-started/configuration

Use the --help flag with opal-server or opal-client to view all available command-line options. To see options for a specific command, append the command name before --help.

```bash
# View all options  
opal-server --help  
opal-client --help  
  
# View specific command options  
opal-server run --help  
opal-client run --help  
```

--------------------------------

### Get User Data from OPA

Source: https://docs.opal.ac/getting-started/quickstart/opal-playground/send-queries-to-opa

Retrieve user data and role assignments from the OPA Agent. This GET request targets the /v1/data/users endpoint.

```shell
curl --request GET 'http://localhost:8181/v1/data/users' --header 'Content-Type: application/json' | python -m json.tool
```

--------------------------------

### Initial User Data Configuration

Source: https://docs.opal.ac/getting-started/quickstart/opal-playground/publishing-data-update

This JSON snippet shows the initial configuration for user 'bob', including roles and location, which allows access in the first query.

```json
{
    "bob": {
        "roles": ["employee", "billing"],
        "location": {
            "country": "US",
            "ip": "8.8.8.8"
        }
    }
}
```

--------------------------------

### Get Policies

Source: https://docs.opal.ac/tutorials/cedar

Retrieves the currently active Cedar policies.

```APIDOC
## GET /policies

### Description
Retrieves the currently active Cedar policies.

### Method
GET

### Endpoint
/policies
```

--------------------------------

### Get Data

Source: https://docs.opal.ac/tutorials/cedar

Retrieves the current data used by the Cedar policies.

```APIDOC
## GET /data

### Description
Retrieves the current data used by the Cedar policies.

### Method
GET

### Endpoint
/data
```

--------------------------------

### Fetch Complete Policy Bundle

Source: https://docs.opal.ac/tutorials/track_a_git_repo

Use this command to fetch a complete bundle of policy files from the repository. The 'path=.' parameter includes all policy files in the root directory.

```bash
curl --request GET 'https://opal.permit.io/policy?path=.'
```

--------------------------------

### Get Current Connectivity Status

Source: https://docs.opal.ac/tutorials/opal_server_connectivity

Retrieves the current status of OPAL server connectivity and offline mode.

```APIDOC
## GET /opal-server/connectivity

### Description
Retrieves the current status of OPAL server connectivity and whether offline mode is enabled.

### Method
GET

### Endpoint
/opal-server/connectivity

### Response
#### Success Response (200)
- **opal_server_connectivity_disabled** (boolean) - Indicates if the OPAL server connectivity is disabled.
- **offline_mode_enabled** (boolean) - Indicates if the offline mode is enabled.

### Response Example
```json
{
  "opal_server_connectivity_disabled": true,
  "offline_mode_enabled": true
}
```
```

--------------------------------

### Get Server Statistics

Source: https://docs.opal.ac/opal-plus/features

Retrieves basic statistics about the OPAL+ server, such as uptime, version, and client/server counts.

```APIDOC
## GET /stats

### Description
Retrieves basic statistics about the OPAL+ server.

### Method
GET

### Endpoint
/stats

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://opal_server:8181/stats -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **uptime** (string) - The uptime of the server.
- **version** (string) - The version of OPAL+.
- **client_count** (integer) - The number of connected clients.
- **server_count** (integer) - The number of connected servers.

#### Response Example
```json
{
  "uptime": "2024-07-14T14:55:02.710Z",
  "version": "0.7.8",
  "client_count": 1,
  "server_count": 1
}
```
```

--------------------------------

### OPA Healthcheck Full Status Output

Source: https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks

This is an example of the JSON output when querying the full OPA healthcheck status.

```json
{
  "result": {
    "healthy": true,
    "last_data_transaction": {
      "actions": ["set_policy_data"],
      "error": "",
      "id": "476f290d23964099b5ddd8f10e46873d",
      "success": true
    },
    "last_policy_transaction": {
      "actions": ["set_policies"],
      "error": "",
      "id": "0e45f42f3d7da9b343f5c199934b4bf89a9cacbd",
      "success": true
    },
    "ready": true
  }
}
```

--------------------------------

### FetchProvider __aenter__ Method for Context Management

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Initializes resources like database connections and transactions within an asynchronous context manager. Use for I/O-bound operations and resource guarding.

```python
async def __aenter__(self):

    # initializing parameters from the event/config

    self._event: PostgresFetchEvent

    dsn: str = self._event.url

    connection_params: dict = {} if self._event.config.connection_params is None else self._event.config.connection_params.dict(exclude_none=True)

  

    # connect to the postgres database

    self._connection: asyncpg.Connection = await asyncpg.connect(dsn, **connection_params)

  

    # start a readonly transaction (we don't want OPAL client writing data due to security!)

    self._transaction: Transaction = self._connection.transaction(readonly=True)

    await self._transaction.__aenter__()

  

    return self

```

--------------------------------

### Run OPAL Client Locally

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Run the OPAL client locally using the `opal-client run` command for easier debugging and testing of fetch providers. Alternatively, use `uvicorn` directly.

```bash
opal-client run

```

--------------------------------

### Get Detailed Statistics

Source: https://docs.opal.ac/opal-plus/features

Retrieves detailed information about OPAL+ clients and servers, including their connection status and topics.

```APIDOC
## GET /statistics

### Description
Retrieves detailed information about OPAL+ clients and servers.

### Method
GET

### Endpoint
/statistics

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://opal_server:8181/statistics -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **uptime** (string) - The uptime of the server.
- **version** (string) - The version of OPAL+.
- **clients** (object) - Information about connected clients.
  - **client_id** (string) - The unique identifier for the client.
  - **rpc_id** (string) - The RPC ID of the client connection.
  - **topics** (array of strings) - The topics subscribed to by the client.
- **servers** (array of strings) - A list of server identifiers.

#### Response Example
```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"
  ]
}
```
```

--------------------------------

### Building a Custom OPAL Client Container

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Build your customized OPAL client Docker image using the Dockerfile created in the previous step. Replace 'yourcompany/opal-client' with your desired image name and tag.

```bash
docker build -t yourcompany/opal-client -f custom_client.Dockerfile .

```

--------------------------------

### Configure Data Configuration Fetch Route

Source: https://docs.opal.ac/getting-started/configuration

Set the URL route to fetch the full basic configuration of data. Defaults to '/data/config'.

```bash
export OPAL_DATA_CONFIG_ROUTE="/api/v1/data/config"
```

--------------------------------

### Configure OPAL Monitoring and Logging

Source: https://docs.opal.ac/getting-started/configuration

Enhance monitoring and logging by enabling PID in log format, setting the log level, and enabling statistics.

```bash
# Enhanced logging and statistics  
export OPAL_LOG_FORMAT_INCLUDE_PID=true  
export OPAL_LOG_LEVEL=INFO  
export OPAL_STATISTICS_ENABLED=true  
```

--------------------------------

### Example JWT Token Output

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-client/obtain-jwt-token

Illustrates the expected JSON structure returned by the token endpoint, containing the JWT in the 'token' field.

```json
{
    "token": "eyJ0...8wsk",
    "type": "bearer",
    "details": { ... }
}

```

--------------------------------

### Configure OPAL Client Environment Variables

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-client/lets-run-the-client

Set these environment variables to configure the OPAL client. Ensure you replace placeholders with your actual token, server URL, and desired data topics.

```bash
# let's say this is the (shortened) token we obtained from opal server  

export OPAL_CLIENT_TOKEN=eyJ0...8wsk  

# and this is where we deployed opal server  

export OPAL_SERVER_URL=https://opal.yourdomain.com  

# and let's say we subscribe to a specific tenant's data updates (i.e: `tenant1`)  

export OPAL_DATA_TOPICS=policy_data/tenant1  
```

--------------------------------

### Configure OPAL Client Environment Variables

Source: https://docs.opal.ac/getting-started/configuration

Set environment variables for the OPAL client to connect to the server, authenticate, and specify the policy engine.

```bash
# Connect to your OPAL server  
export OPAL_SERVER_URL=http://localhost:7002  
  
# Authentication token (change in production!)  
export OPAL_CLIENT_TOKEN=your-secret-token  
  
# Policy engine type (OPA is default, Cedar also available)  
export OPAL_POLICY_STORE_TYPE=opa  
```

--------------------------------

### Configure OPAL Security Settings

Source: https://docs.opal.ac/getting-started/configuration

Enable secure mode with proper authentication keys and tokens, and configure HTTPS for server communication.

```bash
# Enable secure mode with proper authentication  
export OPAL_AUTH_PRIVATE_KEY="your-rsa-private-key"  
export OPAL_AUTH_PUBLIC_KEY="your-rsa-public-key"  
export OPAL_AUTH_MASTER_TOKEN="secure-random-token"  
  
# Use HTTPS  
export OPAL_SERVER_URL=https://opal.your-domain.com  
```

--------------------------------

### Configure OPAL-server to use Kafka

Source: https://docs.opal.ac/tutorials/run_opal_with_kafka

Set the OPAL_BROADCAST_URI environment variable to point to your Kafka instance. The 'kafka://' prefix indicates Kafka as the backend.

```bash
export OPAL_BROADCAST_URI=kafka://kafka-host-name:9092
```

--------------------------------

### Configure Proxy with Authentication

Source: https://docs.opal.ac/tutorials/setup_opal_behind_proxy

If your proxy requires authentication, include username and password in the proxy URL for HTTP_PROXY and HTTPS_PROXY environment variables.

```bash
HTTP_PROXY=http://username:password@proxy.example.com:8080  
HTTPS_PROXY=http://username:password@proxy.example.com:8080  
```

--------------------------------

### Encoding Data Source Configuration with Python

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-server/data-sources

Demonstrates how to use Python's `json.dumps()` to convert a data source configuration dictionary into a JSON string suitable for environment variables.

```python
x = {
    "config": {
        "entries": [
            ... # removed for brevity
        ]
    }
}

import json
json.dumps(x)
```

--------------------------------

### Basic Fetch Provider Project File Hierarchy

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

The minimum file tree structure for an OPAL fetch provider package.

```plaintext
.  

├── LICENSE  
├── README.md  
├── opal_fetcher_postgres  
├── requirements.txt  
├── setup.py  

```

--------------------------------

### Run OPAL Client with Uvicorn

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Run the OPAL client using `uvicorn` directly for local development and debugging. This provides an alternative to the `opal-client run` command.

```bash
uvicorn opal_client.main:app

```

--------------------------------

### Export OPAL+ Configuration

Source: https://docs.opal.ac/opal-plus/troubleshooting

Run this command to export your current OPAL+ configuration. Remember to censor sensitive information before sharing.

```bash
opal-client print-config
```

--------------------------------

### Configure HTTP Proxy Environment Variables

Source: https://docs.opal.ac/tutorials/setup_opal_behind_proxy

Set these environment variables to configure the HTTP proxy for OPAL Client. Use HTTP_PROXY for http:// URLs, HTTPS_PROXY for https:// URLs, and ALL_PROXY as a fallback. NO_PROXY specifies hosts to bypass the proxy.

```bash
# HTTP proxy for http:// URLs  
HTTP_PROXY=http://proxy.example.com:8080  

# HTTPS proxy for https:// URLs  
HTTPS_PROXY=http://proxy.example.com:8080  

# Proxy for all protocols (fallback if protocol-specific not set)  
ALL_PROXY=http://proxy.example.com:8080  

# Comma-separated list of hosts to bypass proxy  
NO_PROXY=localhost,127.0.0.1,::1  
```

--------------------------------

### Get Current OPAL Server Connectivity Status

Source: https://docs.opal.ac/tutorials/opal_server_connectivity

Use this curl command to check the current connectivity status of the OPAL server. This is useful for verifying if the client is connected or disconnected.

```curl
curl http://localhost:7000/opal-server/connectivity
```

--------------------------------

### Dockerfile for PyPI Published Package

Source: https://docs.opal.ac/tutorials/write_your_own_fetch_provider

Build a custom Docker image for OPAL when your custom fetch provider is published to PyPI. This simplified Dockerfile installs the package directly using pip.

```dockerfile
# inherits all behavior defined in the official OPAL-client image  
FROM permitio/opal-client:latest  

# installs the python package inside the container (from pip / PyPI)  
RUN pip install --user opal-fetcher-postgres  
```

--------------------------------

### Add First Tenant Configuration

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Adds the configuration for the first tenant (tenant1) to OPAL. This involves specifying the URL of the external data provider and the destination path for the tenant's data.

```bash
curl -X POST http://localhost:7002/data/config \
  -H "Content-Type: application/json" \
  -d '{ \
    "entries": [ \
      { \
        "url": "http://example_external_data_provider:80/acl/tenant1", \
        "topics": ["tenant_data"], \
        "dst_path": "/acl/tenant1" \
      } \
    ], \
    "reason": "Add tenant1 data source" \
  }'
```

--------------------------------

### Query User Data from OPA

Source: https://docs.opal.ac/tutorials/track_an_api_bundle_server

Send a GET request to the OPA /v1/data/users endpoint to retrieve user role assignments and metadata. The OPA REST API is accessible on port 8181.

```bash
curl --request GET 'http://localhost:8181/v1/data/users' --header 'Content-Type: application/json' | python -m json.tool  
```

--------------------------------

### Get Opal Client Image for Standalone OPA

Source: https://docs.opal.ac/getting-started/running-opal/run-opal-client/get-client-image

Use this command to pull the Opal client image designed for environments where OPA is already running separately. This variant does not include OPA.

```docker
docker pull permitio/opal-client-standalone
```

--------------------------------

### Configure Data Configuration Route

Source: https://docs.opal.ac/getting-started/configuration

Define the route for all data configuration. Defaults to '/policy-data'.

```bash
export OPAL_ALL_DATA_ROUTE="/config/data"
```

--------------------------------

### Download OPAL Server Docker Image

Source: https://docs.opal.ac/getting-started/running-opal/download-docker-images

Use these commands to pull the OPAL server image. The `latest-alpine` tag provides a smaller image size.

```bash
docker pull permitio/opal-server
```

```bash
docker pull permitio/opal-server:latest-alpine
```

--------------------------------

### Create Internal Scope with REST API

Source: https://docs.opal.ac/overview/scopes

Use a PUT request to the /scopes endpoint to create a new scope. This example configures an 'internal' scope with policies from the 'internal' directory of a Git repository.

```bash
curl --request PUT 'http://opal_server/scopes'  
--header 'Content-Type: application/json'  
--header 'Authorization: $OPAL_TOKEN'  
--data-raw '{  
  "scope_id": "internal",  
  "policy": {  
    "source_type": "git",  
    "url": "https://github.com/company/policy",  
    "auth": {  
      "auth_type": "github_token",  
      "token": "github_token"  
    },  
    "directories": [  
      "internal"  
    ],  
    "extensions": [  
      ".rego",  
      ".json"  
    ],  
    "manifest": ".manifest",  
    "poll_updates": true,  
    "branch": "main"  
  },  
  "data": {  
    "entries": []  
  }  
}'  
```

--------------------------------

### Enable v0 Compatibility Mode

Source: https://docs.opal.ac/tutorials/opa-version-migration

Set the OPAL_OPA_V0_COMPAT environment variable to 'true' to enable v0 compatibility mode. This allows OPA to accept both v0 and v1 syntax.

```bash
export OPAL_OPA_V0_COMPAT=true
```

```bash
export OPAL_OPA_V0_COMPAT=false
```

--------------------------------

### Download OPAL Client Docker Image

Source: https://docs.opal.ac/getting-started/running-opal/download-docker-images

Use these commands to pull the OPAL client image. The `latest-alpine` tag provides a smaller image size.

```bash
docker pull permitio/opal-client
```

```bash
docker pull permitio/opal-client:latest-alpine
```

--------------------------------

### Configure OPAL Performance and Scaling

Source: https://docs.opal.ac/getting-started/configuration

Optimize performance and scaling by setting the number of Uvicorn workers and configuring webhooks for policy updates.

```bash
# Scale with multiple server workers  
export UVICORN_NUM_WORKERS=4  
  
# Use webhooks instead of polling for better performance  
export OPAL_POLICY_REPO_POLLING_INTERVAL=0  
export OPAL_POLICY_REPO_WEBHOOK_SECRET=your-webhook-secret  
```

--------------------------------

### Query OPA Healthcheck Full Status

Source: https://docs.opal.ac/tutorials/healthcheck_policy_and_update_callbacks

Send a GET request to this endpoint to retrieve the complete health status, including the latest policy git hash and last successful data update ID.

```bash
curl --request GET http://localhost:8181/v1/data/system/opal
```

--------------------------------

### Configure OPAL Data Sources

Source: https://docs.opal.ac/FAQ

Configure OPAL to load data from a specified URL. Ensure the URL is accessible from the OPAL client container. This configuration is part of the OPAL client's data loading setup.

```json
{
  "config":{
    "entries":[
      {
        "url":"http://host.docker.internal:8000/permissions.json",
        "topics":["permissions"],
        "dst_path":"/course_permissions"
      }
    ]
  }
}
```

--------------------------------

### OPAL Server Docker Compose Configuration

Source: https://docs.opal.ac/getting-started/quickstart/docker-compose-config/opal-server

Defines the OPAL server service within a Docker Compose setup, specifying image, environment variables for broadcast, policy repository, data sources, and port mappings.

```yaml
services:
  opal_server:
    image: permitio/opal-server:latest
    environment:
      - OPAL_BROADCAST_URI=postgres://postgres:postgres@broadcast_channel:5432/postgres
      - UVICORN_NUM_WORKERS=4
      - OPAL_POLICY_REPO_URL=https://github.com/permitio/opal-example-policy-repo
      - OPAL_POLICY_REPO_POLLING_INTERVAL=30
      - OPAL_DATA_CONFIG_SOURCES={"config":{"entries":[{"url":"http://opal_server:7002/policy-data","topics":["policy_data"],"dst_path":"/static"}]}}
      - OPAL_LOG_FORMAT_INCLUDE_PID=true
    ports:
      - "7002:7002"
    depends_on:
      - broadcast_channel
```

--------------------------------

### Configure Uvicorn Service with Self-Signed Certificates

Source: https://docs.opal.ac/tutorials/use_self_signed_certificates

Launches a uvicorn service using the generated private key and certificate for HTTPS communication. This allows local development over HTTPS.

```bash
uvicorn myservice.main:app --reload --port=8000 --ssl-keyfile=localserver-private.key --ssl-certfile=localserver-cert.crt
```

--------------------------------

### Troubleshoot Tenant Data Issues

Source: https://docs.opal.ac/tutorials/single-topic-multi-tenant

Check topic configuration and client logs to troubleshoot issues where a tenant is not receiving data.

```bash
# Test data endpoint
curl http://localhost:8090/acl/tenant1

# Check client logs
docker logs $(docker compose ps -q opal_client)
```