Setup the SQS Queue

Prerequisites

• AWS account with permissions to create SQS queues, IAM policies.
• AWS CLI v2 installed and configured (aws --version).
• A project-specific queue name and environment information.
• The AWS region and account ID to use for the queue URL.

Step 1 — Create the Source Queue

Naming convention

Use a consistent, environment-specific name, for example:

forge-vesper-connector-<client>-<environment>

Examples: forge-vesper-connector-dummy-prod, forge-vesper-connector-dummy-uat

Queue type: Always create a Standard queue (not FIFO). The connector does not require strict ordering and Standard queues provide higher throughput and the re-delivery semantics the connector depends on.

Option A — AWS Management Console

1. Open the AWS SQS console.
2. Click Create queue.

3. Click Create queue.

4. Under Type, select Standard.
5. Enter the queue Name following the naming convention above.
6. Expand the Configuration section and set the attributes described below.

Recommended Queue Attributes

Attribute	Recommended value	AWS CLI key
Queue type	Standard	FifoQueue: (omit)
Message retention period	4 days (345600 s) with DLQ; 1 day (86400 s) without	MessageRetentionPeriod
Visibility timeout	120 s	VisibilityTimeout
Receive message wait time	20 s	ReceiveMessageWaitTimeSeconds

7. Click Create queue.
8. Note the Queue URL shown on the details page. You will need this for the connector configuration (for example: https://sqs.eu-central-1.amazonaws.com/123456789012/forge-vesper-connector-dummy-prod).

Option B — AWS CLI

aws sqs create-queue \
  --queue-name forge-vesper-connector-dummy-prod \
  --attributes \
    'MessageRetentionPeriod="345600"' \
    'VisibilityTimeout="120"' \
    'ReceiveMessageWaitTimeSeconds="20"'

The response contains the QueueUrl:

{
    "QueueUrl": "https://sqs.eu-central-1.amazonaws.com/123456789012/forge-vesper-connector-dummy-prod"
}

---

Step 2 — Configure the Dead Letter Queue (DLQ) — Optional

A DLQ is a separate SQS queue where messages are automatically moved after they have failed processing a configurable number of times (maxReceiveCount).

Step 2a — Create the DLQ

Console:

1. In the SQS console, click Create queue.
2. Select Standard.
3. Name it using the same convention with a -dlq suffix: forge-vesper-connector-dummy-prod-dlq.
4. Set Message retention period to 14 days (1209600 s).
5. Set Visibility timeout to 30 seconds (messages in the DLQ are not processed by the connector so a short timeout is fine).
6. Click Create queue.

CLI:

aws sqs create-queue \
  --queue-name forge-vesper-connector-dummy-prod-dlq \
  --attributes \
    'MessageRetentionPeriod="1209600"' \
    'VisibilityTimeout="30"'

Step 2b — Attach the DLQ to the Source Queue

Console:

1. Open the source queue in the SQS console.
2. Click Edit.
3. Scroll to Dead-letter queue.
4. Toggle Enabled.
5. Select forge-vesper-connector-dummy-prod-dlq from the dropdown.
6. Set Maximum receives to 5.
7. Click Save.

CLI:

DLQ_ARN=$(aws sqs get-queue-attributes \
  --queue-url https://sqs.<region>.amazonaws.com/<account>/forge-vesper-connector-dummy-prod-dlq \
  --attribute-names QueueArn \
  --query 'Attributes.QueueArn' \
  --output text)

aws sqs set-queue-attributes \
  --queue-url https://sqs.<region>.amazonaws.com/<account>/forge-vesper-connector-dummy-prod \
  --attributes \
    "RedrivePolicy={\"deadLetterTargetArn\":\"${DLQ_ARN}\",\"maxReceiveCount\":\"5\"}"

---

Step 3 — Verify the Setup

Verify queue attributes

aws sqs get-queue-attributes \
  --queue-url https://sqs.<region>.amazonaws.com/<account>/forge-vesper-connector-dummy-prod \
  --attribute-names All

Confirm the output shows:

• VisibilityTimeout ≥ connector's VisibilityTimeoutSeconds
• MessageRetentionPeriod = 345600 (4 days) with DLQ, or 86400 (1 day) without
• ReceiveMessageWaitTimeSeconds = 20
• RedrivePolicy contains the DLQ ARN and maxReceiveCount = 5 (if configured)

---

Step 4 — IAM Permissions

The FORGE VESPER Connector IAM role needs the following permissions on the source queue only. The connector never writes to or reads from the DLQ directly — SQS handles the redrive internally.

Minimum required permissions

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowQueueOperations",
      "Effect": "Allow",
      "Action": [
        "sqs:CreateQueue",
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:ChangeMessageVisibility",
        "sqs:GetQueueAttributes"
      ],
      "Resource": "arn:aws:sqs:<region>:<account>:forge-vesper-connector-dummy-prod"
    }
  ]
}

Permission	Why it is needed
sqs:CreateQueue	Required at startup — EnsureQueueHostedService calls CreateQueue (idempotent: returns the existing queue if it already exists). Without this permission the connector fails to start.
sqs:ReceiveMessage	Poll the queue for new messages.
sqs:DeleteMessage	Acknowledge (ACK) successfully processed messages.
sqs:ChangeMessageVisibility	Extend the visibility timeout via the heartbeat while processing is in progress.
sqs:GetQueueAttributes	Used internally by the AWS SDK during queue operations.

Do not grant sqs:DeleteQueue or sqs:SetQueueAttributes to the connector role — the connector does not need to delete or modify queue settings at runtime.