Skip to content

Commit d918829

Browse files
teanasteanas
authored
Merge branch 'main' into feature/enable-aggr-vcs
2 parents bc1110b + aaee62f commit d918829

2 files changed

Lines changed: 275 additions & 1 deletion

File tree

‎RedisPlugins.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# ACA-Py Redis Plugins
2+
# [aries-acapy-plugin-redis-events](https://github.com/bcgov/aries-acapy-plugin-redis-events/blob/master/README.md) [`redis_queue`]
3+
4+
<!-- Adopted from aries-acapy-cache-redis/README.md -->
5+
It provides a mechansim to persists both inbound and outbound messages using redis, deliver messages and webhooks, and dispatch events.
6+
7+
More details can be found [here](https://github.com/bcgov/aries-acapy-plugin-redis-events/blob/master/README.md).
8+
9+
### <b>Plugin configuration</b> [`yaml`]
10+
```
11+
redis_queue:
12+
connection:
13+
connection_url: "redis://default:test1234@172.28.0.103:6379"
14+
15+
### For Inbound ###
16+
inbound:
17+
acapy_inbound_topic: "acapy_inbound"
18+
acapy_direct_resp_topic: "acapy_inbound_direct_resp"
19+
20+
### For Outbound ###
21+
outbound:
22+
acapy_outbound_topic: "acapy_outbound"
23+
mediator_mode: false
24+
25+
### For Event ###
26+
event:
27+
event_topic_maps:
28+
^acapy::webhook::(.*)$: acapy-webhook-$wallet_id
29+
^acapy::record::([^:]*)::([^:]*)$: acapy-record-with-state-$wallet_id
30+
^acapy::record::([^:])?: acapy-record-$wallet_id
31+
acapy::basicmessage::received: acapy-basicmessage-received
32+
acapy::problem_report: acapy-problem_report
33+
acapy::ping::received: acapy-ping-received
34+
acapy::ping::response_received: acapy-ping-response_received
35+
acapy::actionmenu::received: acapy-actionmenu-received
36+
acapy::actionmenu::get-active-menu: acapy-actionmenu-get-active-menu
37+
acapy::actionmenu::perform-menu-action: acapy-actionmenu-perform-menu-action
38+
acapy::keylist::updated: acapy-keylist-updated
39+
acapy::revocation-notification::received: acapy-revocation-notification-received
40+
acapy::revocation-notification-v2::received: acapy-revocation-notification-v2-received
41+
acapy::forward::received: acapy-forward-received
42+
event_webhook_topic_maps:
43+
acapy::basicmessage::received: basicmessages
44+
acapy::problem_report: problem_report
45+
acapy::ping::received: ping
46+
acapy::ping::response_received: ping
47+
acapy::actionmenu::received: actionmenu
48+
acapy::actionmenu::get-active-menu: get-active-menu
49+
acapy::actionmenu::perform-menu-action: perform-menu-action
50+
acapy::keylist::updated: keylist
51+
deliver_webhook: true
52+
```
53+
- `redis_queue.connection.connection_url`: This is required and is expected in `redis://{username}:{password}@{host}:{port}` format.
54+
- `redis_queue.inbound.acapy_inbound_topic`: This is the topic prefix for the inbound message queues. Recipient key of the message are also included in the complete topic name. The final topic will be in the following format `acapy_inbound_{recip_key}`
55+
- `redis_queue.inbound.acapy_direct_resp_topic`: Queue topic name for direct responses to inbound message.
56+
- `redis_queue.outbound.acapy_outbound_topic`: Queue topic name for the outbound messages. Used by Deliverer service to deliver the payloads to specified endpoint.
57+
- `redis_queue.outbound.mediator_mode`: Set to true, if using Redis as a http bridge when setting up a mediator agent. By default, it is set to false.
58+
- `event.event_topic_maps`: Event topic map
59+
- `event.event_webhook_topic_maps`: Event to webhook topic map
60+
- `event.deliver_webhook`: When set to true, this will deliver webhooks to endpoints specified in `admin.webhook_urls`. By default, set to true.
61+
62+
### <b>Usage</b>
63+
64+
#### <b>With Docker</b>
65+
Running the plugin with docker is simple. An
66+
example [docker-compose.yml](https://github.com/bcgov/aries-acapy-plugin-redis-events/blob/master/docker/docker-compose.yml) file is available which launches both ACA-Py with redis and an accompanying Redis cluster.
67+
68+
```sh
69+
$ docker-compose up --build -d
70+
```
71+
More details can be found [here](https://github.com/bcgov/aries-acapy-plugin-redis-events/blob/master/docker/README.md).
72+
73+
#### <b>Without Docker</b>
74+
Installation
75+
```
76+
pip install git+https://github.com/bcgov/aries-acapy-plugin-redis-events.git
77+
```
78+
Startup ACA-Py with `redis_queue` plugin loaded
79+
```
80+
docker network create --subnet=172.28.0.0/24 `network_name`
81+
export REDIS_PASSWORD=" ... As specified in redis_cluster.conf ... "
82+
export NETWORK_NAME="`network_name`"
83+
aca-py start \
84+
--plugin redis_queue.v1_0.events \
85+
--plugin-config plugins-config.yaml \
86+
-it redis_queue.v1_0.inbound redis 0 -ot redis_queue.v1_0.outbound
87+
# ... the remainder of your startup arguments
88+
```
89+
90+
Regardless of the options above, you will need to startup `deliverer` and `relay`/`mediator` service as a bridge to receive inbound messages. Consider the following to build your `docker-compose` file which should also start up your redis cluster:
91+
- Relay + Deliverer
92+
```
93+
relay:
94+
image: redis-relay
95+
build:
96+
context: ..
97+
dockerfile: redis_relay/Dockerfile
98+
ports:
99+
- 7001:7001
100+
- 80:80
101+
environment:
102+
- REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379
103+
- TOPIC_PREFIX=acapy
104+
- STATUS_ENDPOINT_HOST=0.0.0.0
105+
- STATUS_ENDPOINT_PORT=7001
106+
- STATUS_ENDPOINT_API_KEY=test_api_key_1
107+
- INBOUND_TRANSPORT_CONFIG=[["http", "0.0.0.0", "80"]]
108+
- TUNNEL_ENDPOINT=http://relay-tunnel:4040
109+
- WAIT_BEFORE_HOSTS=15
110+
- WAIT_HOSTS=redis-node-3:6379
111+
- WAIT_HOSTS_TIMEOUT=120
112+
- WAIT_SLEEP_INTERVAL=1
113+
- WAIT_HOST_CONNECT_TIMEOUT=60
114+
depends_on:
115+
- redis-cluster
116+
- relay-tunnel
117+
networks:
118+
- acapy_default
119+
deliverer:
120+
image: redis-deliverer
121+
build:
122+
context: ..
123+
dockerfile: redis_deliverer/Dockerfile
124+
ports:
125+
- 7002:7002
126+
environment:
127+
- REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379
128+
- TOPIC_PREFIX=acapy
129+
- STATUS_ENDPOINT_HOST=0.0.0.0
130+
- STATUS_ENDPOINT_PORT=7002
131+
- STATUS_ENDPOINT_API_KEY=test_api_key_2
132+
- WAIT_BEFORE_HOSTS=15
133+
- WAIT_HOSTS=redis-node-3:6379
134+
- WAIT_HOSTS_TIMEOUT=120
135+
- WAIT_SLEEP_INTERVAL=1
136+
- WAIT_HOST_CONNECT_TIMEOUT=60
137+
depends_on:
138+
- redis-cluster
139+
networks:
140+
- acapy_default
141+
```
142+
- Mediator + Deliverer
143+
```
144+
mediator:
145+
image: acapy-redis-queue
146+
build:
147+
context: ..
148+
dockerfile: docker/Dockerfile
149+
ports:
150+
- 3002:3001
151+
depends_on:
152+
- deliverer
153+
volumes:
154+
- ./configs:/home/indy/configs:z
155+
- ./acapy-endpoint.sh:/home/indy/acapy-endpoint.sh:z
156+
environment:
157+
- WAIT_BEFORE_HOSTS=15
158+
- WAIT_HOSTS=redis-node-3:6379
159+
- WAIT_HOSTS_TIMEOUT=120
160+
- WAIT_SLEEP_INTERVAL=1
161+
- WAIT_HOST_CONNECT_TIMEOUT=60
162+
- TUNNEL_ENDPOINT=http://mediator-tunnel:4040
163+
networks:
164+
- acapy_default
165+
entrypoint: /bin/sh -c '/wait && ./acapy-endpoint.sh poetry run aca-py "$$@"' --
166+
command: start --arg-file ./configs/mediator.yml
167+
168+
deliverer:
169+
image: redis-deliverer
170+
build:
171+
context: ..
172+
dockerfile: redis_deliverer/Dockerfile
173+
depends_on:
174+
- redis-cluster
175+
ports:
176+
- 7002:7002
177+
environment:
178+
- REDIS_SERVER_URL=redis://default:test1234@172.28.0.103:6379
179+
- TOPIC_PREFIX=acapy
180+
- STATUS_ENDPOINT_HOST=0.0.0.0
181+
- STATUS_ENDPOINT_PORT=7002
182+
- STATUS_ENDPOINT_API_KEY=test_api_key_2
183+
- WAIT_BEFORE_HOSTS=15
184+
- WAIT_HOSTS=redis-node-3:6379
185+
- WAIT_HOSTS_TIMEOUT=120
186+
- WAIT_SLEEP_INTERVAL=1
187+
- WAIT_HOST_CONNECT_TIMEOUT=60
188+
networks:
189+
- acapy_default
190+
```
191+
192+
Both relay and mediator [demos](https://github.com/bcgov/aries-acapy-plugin-redis-events/tree/master/demo) are also available.
193+
194+
# [aries-acapy-cache-redis](https://github.com/Indicio-tech/aries-acapy-cache-redis/blob/main/README.md) [`redis_cache`]
195+
196+
<!-- Adopted from aries-acapy-cache-redis/README.md -->
197+
ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose
198+
of this plugin is to allow ACA-Py to use Redis as the storage medium for it's
199+
caching needs.
200+
201+
More details can be found [here](https://github.com/Indicio-tech/aries-acapy-cache-redis/blob/main/README.md).
202+
203+
### <b>Plugin configuration</b> [`yaml`]
204+
```
205+
redis_cache:
206+
connection: "redis://default:test1234@172.28.0.103:6379"
207+
max_connection: 50
208+
credentials:
209+
username: "default"
210+
password: "test1234"
211+
ssl:
212+
cacerts: ./ca.crt
213+
```
214+
- `redis_cache.connection`: This is required and is expected in `redis://{username}:{password}@{host}:{port}` format.
215+
- `redis_cache.max_connection`: Maximum number of redis pool connections. Default: 50
216+
- `redis_cache.credentials.username`: Redis instance username
217+
- `redis_cache.credentials.password`: Redis instance password
218+
- `redis_cache.ssl.cacerts`
219+
220+
### <b>Usage</b>
221+
222+
#### <b>With Docker</b>
223+
- Running the plugin with docker is simple and straight-forward. There is an
224+
example [docker-compose.yml](https://github.com/Indicio-tech/aries-acapy-cache-redis/blob/main/docker-compose.yml) file in the root of the
225+
project that launches both ACA-Py and an accompanying Redis instance. Running
226+
it is as simple as:
227+
228+
```sh
229+
$ docker-compose up --build -d
230+
```
231+
232+
- To launch ACA-Py with an accompanying redis cluster of 6 nodes [3 primaries and 3 replicas], please refer to example [docker-compose.cluster.yml](https://github.com/Indicio-tech/aries-acapy-cache-redis/blob/main/docker-compose.cluster.yml) and run the following:
233+
234+
Note: Cluster requires external docker network with specified subnet
235+
236+
```sh
237+
$ docker network create --subnet=172.28.0.0/24 `network_name`
238+
$ export REDIS_PASSWORD=" ... As specified in redis_cluster.conf ... "
239+
$ export NETWORK_NAME="`network_name`"
240+
$ docker-compose -f docker-compose.cluster.yml up --build -d
241+
```
242+
#### <b>Without Docker</b>
243+
Installation
244+
```
245+
pip install git+https://github.com/Indicio-tech/aries-acapy-cache-redis.git
246+
```
247+
Startup ACA-Py with `redis_cache` plugin loaded
248+
```
249+
aca-py start \
250+
--plugin acapy_cache_redis.v0_1 \
251+
--plugin-config plugins-config.yaml \
252+
# ... the remainder of your startup arguments
253+
```
254+
or
255+
```
256+
aca-py start \
257+
--plugin acapy_cache_redis.v0_1 \
258+
--plugin-config-value "redis_cache.connection=redis://redis-host:6379/0" \
259+
--plugin-config-value "redis_cache.max_connections=90" \
260+
--plugin-config-value "redis_cache.credentials.username=username" \
261+
--plugin-config-value "redis_cache.credentials.password=password" \
262+
# ... the remainder of your startup arguments
263+
```
264+
## <b>RedisCluster</b>
265+
266+
If you startup a redis cluster and an ACA-Py agent loaded with either `redis_queue` or `redis_cache` plugin or both, then during the initialization of the plugin, it will bind an instance of `redis.asyncio.RedisCluster` [onto the `root_profile`]. Other plugin will have access to this redis client for it's functioning. This is done for efficiency and to avoid duplication of resources.

‎scripts/run_docker‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ for arg in "$@"; do
3333
done
3434
fi
3535
done
36+
ACAPY_NETWORK_NAME="${NETWORK_NAME}"
3637
if [ -n "${ENABLE_PTVSD}" ]; then
3738
ARGS="${ARGS} -e ENABLE_PTVSD=\"${ENABLE_PTVSD}\" -p $PTVSD_PORT:$PTVSD_PORT"
3839
fi
@@ -48,5 +49,12 @@ if [ "$OSTYPE" == "msys" ]; then
4849
fi
4950

5051
RAND_NAME=$(env LC_ALL=C tr -dc 'a-zA-Z0-9' < /dev/urandom | fold -w 16 | head -n 1)
51-
$CONTAINER_RUNTIME run --rm -ti --name "aries-cloudagent-runner_${RAND_NAME}" \
52+
if [ -z "$NETWORK_NAME" ]; then
53+
echo "No Docker network specified."
54+
$CONTAINER_RUNTIME run --rm -ti --name "aries-cloudagent-runner_${RAND_NAME}" \
5255
$ARGS aries-cloudagent-run "$@"
56+
else
57+
echo "${ACAPY_NETWORK_NAME} Docker network specified."
58+
$CONTAINER_RUNTIME run --rm -ti --network $ACAPY_NETWORK_NAME --name "aries-cloudagent-runner_${RAND_NAME}" \
59+
$ARGS aries-cloudagent-run "$@"
60+
fi

0 commit comments

Comments
 (0)