Skip to content

Commit 8b16155

Browse files
leggetterleggetter
authored
docs: Delivery and destination queue QA and setup (#287)
* chore(portal): sort by destination type label * chore(portal): show non-senstive credential values * chore(portal): remove min-height on destinations creation * wip: publish queue instruction updates * chore: use event.topic as routing_key for rabbitmq * chore(portal): use Checkbox component in DestinationConfig * chore(portal): basic RabbitMQ config instructions * chore: use event.topic as routing_key for rabbitmq * chore(examples): update publish example * chore(examples): meta_data -> metadata * chore: update AWS SQS instructions * feat(examples): RabbitMQ publish queue * chore(docs): add destination_id as optional to publish request * feat(docs): publish from RabbitMQ basic guide * feat(docs): SQS docs and example * chore(examples): update README * chore(portal): small event and attempt payload styling changes
1 parent 43d2794 commit 8b16155

File tree

24 files changed

+2162
-220
lines changed

24 files changed

+2162
-220
lines changed

‎.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ RABBITMQ_LOG_QUEUE="outpost-log"
4747
## RabbitMQ
4848
# PUBLISH_RABBITMQ_SERVER_URL="amqp://guest:guest@rabbitmq:5672"
4949
# PUBLISH_RABBITMQ_QUEUE="publish"
50+
# PUBLISH_RABBITMQ_EXCHANGE="outpost"
5051

5152
## AWS SQS
5253
# PUBLISH_AWS_SQS_ENDPOINT="http://aws:4566"

‎docs/pages/guides/publish-from-rabbitmq.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: "Publish from RabbitMQ"
3+
---
4+
5+
This guide provides information on using RabbitMQ to publish events to Outpost.
6+
7+
## Message Structure
8+
9+
RabbitMQ messages should have the same payload structure as the [Publish API endpoint](/docs/references/api#publish).
10+
11+
```json
12+
{
13+
"tenant_id": "<TENANT_ID>",
14+
"destination_id": "<DESTINATION_ID>", // Optional. Provide a way of routing events to a specific destination
15+
"topic": "topic.name", // Topic defined in TOPICS environment variable
16+
"eligible_for_retry": true | false, // Should event delivery be retried
17+
"metadata": Payload, // can by any JSON payload,
18+
"data": Payload // can by any JSON payload
19+
}
20+
```
21+
22+
## Configuration
23+
24+
Provide Outpost with connection and routing information for your RabbitMQ instance used for publishing events.
25+
26+
### Environment Variables
27+
28+
```
29+
PUBLISH_RABBITMQ_SERVER_URL="<SERVER_URL>"
30+
PUBLISH_RABBITMQ_EXCHANGE="<EXCHANGE_NAME>"
31+
PUBLISH_RABBITMQ_QUEUE="<QUEUE_NAME>"
32+
```
33+
34+
#### Example
35+
36+
```
37+
PUBLISH_RABBITMQ_SERVER_URL="amqp://guest:guest@localhost:5673"
38+
PUBLISH_RABBITMQ_EXCHANGE="outpost"
39+
PUBLISH_RABBITMQ_QUEUE="publish"
40+
```
41+
42+
### YAML
43+
44+
```yaml
45+
mqs:
46+
publishmq:
47+
rabbitmq:
48+
server_url: <SERVER_URL>
49+
exchange: <EXCHANGE_NAME>
50+
queue: <QUEUE_NAME>
51+
```
52+
53+
#### Example
54+
55+
```yaml
56+
publishmq:
57+
rabbitmq:
58+
server_url: amqp://guest:guest@localhost:5673
59+
exchange: outpost
60+
queue: publish
61+
```
62+
63+
### Troubleshooting
64+
65+
- [Ask a question](https://github.com/hookdeck/outpost/discussions/new?category=q-a)
66+
- [Report a bug](https://github.com/hookdeck/outpost/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%F0%9F%90%9B+Bug+Report%3A+)
67+
- [Request a feature](https://github.com/hookdeck/outpost/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%F0%9F%9A%80+Feature%3A+)

‎docs/pages/guides/publish-from-sqs.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: "Publish from SQS"
3+
---
4+
5+
This guide provides information on using SQS to publish events to Outpost.
6+
7+
## Message Structure
8+
9+
SQS messages should have the same payload structure as the [Publish API endpoint](/docs/references/api#publish).
10+
11+
```json
12+
{
13+
"tenant_id": "<TENANT_ID>",
14+
"destination_id": "<DESTINATION_ID>", // Optional. Provide a way of routing events to a specific destination
15+
"topic": "topic.name", // Topic defined in TOPICS environment variable
16+
"eligible_for_retry": true | false, // Should event delivery be retried
17+
"metadata": Payload, // can by any JSON payload,
18+
"data": Payload // can by any JSON payload
19+
}
20+
```
21+
22+
## Configuration
23+
24+
Provide Outpost with connection and routing information for your RabbitMQ instance used for publishing events.
25+
26+
### Environment Variables
27+
28+
```
29+
PUBLISH_AWS_SQS_REGION="<REGION>"
30+
PUBLISH_AWS_SQS_QUEUE="<QUEUE_NAME>"
31+
PUBLISH_AWS_SQS_ACCESS_KEY_ID="<KEY_ID>"
32+
PUBLISH_AWS_SQS_SECRET_ACCESS_KEY="<SECRET>"
33+
```
34+
35+
Optionally, you can provide the `PUBLISH_AWS_SQS_ENDPOINT` environment variable to specify the endpoint URL for the SQS service. This can be useful for local development or when using a non-standard SQS endpoint.
36+
37+
#### Example
38+
39+
```
40+
PUBLISH_AWS_SQS_REGION="eu-north-1"
41+
PUBLISH_AWS_SQS_QUEUE="outpost-pub-queue"
42+
PUBLISH_AWS_SQS_ACCESS_KEY_ID="REDACTED"
43+
PUBLISH_AWS_SQS_SECRET_ACCESS_KEY="REDACTED"
44+
```
45+
46+
### YAML
47+
48+
```yaml
49+
mqs:
50+
publishmq:
51+
aws_sqs:
52+
region: <AWS_REGION>
53+
queue: <QUEUE_NAME>
54+
access_key_id: <KEY_ID>
55+
secret_access_key: <SECRET>
56+
57+
# Optional.
58+
# Useful for local development or when using a non-standard SQS endpoint.
59+
endpoint: <URL>
60+
```
61+
62+
#### Example
63+
64+
```yaml
65+
mqs:
66+
publishmq:
67+
aws_sqs:
68+
region: eu-north-1
69+
queue: outpost-pub-queue
70+
access_key_id: REDACTED
71+
secret_access_key: REDACTED
72+
```
73+
74+
### Required Permissions
75+
76+
The following permissions are required for the provided access key:
77+
78+
- `sqs:DeleteMessage`
79+
- `sqs:GetQueueUrl`
80+
- `sqs:ReceiveMessage`
81+
82+
### Troubleshooting
83+
84+
- [Ask a question](https://github.com/hookdeck/outpost/discussions/new?category=q-a)
85+
- [Report a bug](https://github.com/hookdeck/outpost/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%F0%9F%90%9B+Bug+Report%3A+)
86+
- [Request a feature](https://github.com/hookdeck/outpost/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%F0%9F%9A%80+Feature%3A+)

‎docs/pages/references/api.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -347,6 +347,7 @@ Publish an event.
347347
```json
348348
{
349349
"tenant_id": "<TENANT_ID>",
350+
"destination_id": "<DESTINATION_ID>", // Optional. Provide a way of routing events to a specific destination
350351
"topic": "topic.name", // Topic defined in TOPICS environment variable
351352
"eligible_for_retry": true | false, // Should event delivery be retried
352353
"metadata": Payload, // can by any JSON payload,

‎docs/zudoku.config.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,16 @@ const config: ZudokuConfig = {
106106
label: "Migrate to Outpost",
107107
id: "guides/migrate-to-outpost",
108108
},
109+
{
110+
type: "doc",
111+
label: "Publish from RabbitMQ",
112+
id: "guides/publish-from-rabbitmq",
113+
},
114+
{
115+
type: "doc",
116+
label: "Publish from SQS",
117+
id: "guides/publish-from-sqs",
118+
},
109119
{
110120
type: "doc",
111121
label: "Deployment",

‎examples/demos/nodejs/README.md‎

Lines changed: 42 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,22 +26,56 @@ Demonstrates how a migration script could work.
2626

2727
Run with:
2828

29-
```
29+
```sh
3030
npm run migrate
3131
```
3232

33-
## Publish test script
34-
35-
Following the migration you may want to test publishing an event and it being received by a destination.
33+
## Publish via API script
3634

3735
Uses the `REAL_TEST_ENDPOINT` value to identify what to publish.
3836

39-
`src/publish-test.ts`
37+
`src/publish-api.ts`
4038

4139
Run with:
4240

41+
```sh
42+
npm run publish-api
43+
```
44+
45+
## Publish via RabbitMQ script
46+
47+
RabbitMQ is assumed to be accessible via `amqp://guest:guest@localhost:5673`. This can be overridden with the `RABBITMQ_URL` environment variable.
48+
49+
`src/publish-rabbitmq.ts`
50+
51+
Run with:
52+
53+
```sh
54+
npm run publish-rabbitmq
55+
```
56+
57+
## Publish via SQS script
58+
59+
Requires the following environment variables to be set:
60+
4361
```
44-
npm run publish-test
62+
SQS_QUEUE_URL=
63+
AWS_REGION=
64+
AWS_ACCESS_KEY_ID=
65+
AWS_SECRET_ACCESS_SECRET=
66+
```
67+
68+
The user associated with the Access Key must have the following permissions:
69+
70+
- `sqs:SendMessage`
71+
- `sqs:GetQueueAttributes`
72+
73+
`src/publish-sqs.ts`
74+
75+
Run with:
76+
77+
```sh
78+
npm run publish-sqs
4579
```
4680

4781
## Verification script
@@ -54,7 +88,7 @@ This script provides two examples of webhook verification.
5488

5589
Run with:
5690

57-
```
91+
```sh
5892
npm run verify
5993
```
6094

@@ -66,6 +100,6 @@ List the signed portal URLs
66100

67101
Run with:
68102

69-
```
103+
```sh
70104
npm run portal-urls
71105
```

0 commit comments

Comments
 (0)