Moving all docs to docs folder

README.md

@@ -2,8 +2,7 @@
 
 This showcase consists of 4 processes hosting MassTransit message producers and consumers that implement a simplified order processing logic from an e-commerce system.
 
-![System Overview](diagram.svg "width=680")
-
+![System Overview](docs/diagram.svg "width=680")
 
 ## Launching the Showcase in Docker
 
@@ -13,11 +12,12 @@ To help getting started we have created a few docker compose files that orchestr
 Run the docker command below from the `src` folder in a terminal.
 
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env up -d
 ```
 
-### To run against **Azure Service Bus**
+### (Alternative) Run in Docker against **Azure Service Bus**
 
+<details>
 The showcase can also be run using Azure Service Bus rather than RabbitMQ.  
 First configure the access to your Azure Service Bus namespace by editing the variables in `src/asb.env`.
 
@@ -28,25 +28,33 @@ CONNECTIONSTRING="Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccess
 Run docker command below from the `src` folder in a terminal.
 
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env up -d
 ```
 
-## Running from an IDE
+</details>
+
+### (Alternative) Run from an IDE
 
+<details>
 > [!WARNING]
 > When using Visual Studio, ensure you have the "Enable Multi-Project Launch profiles" setting on. Allow Visual Studio 2022 "multi-launch" so you can easily select the profile you want to run.
 >
 > It can be activated by accessing the Tools menu -> Manage preview features- Enable Multi-Project Launch profiles.
 
-To start the required infrastructure run the following docker command below from the `src` folder in a terminal.
+To start the required infrastructure for the showcase, run one of the docker command below from the `src` folder in a terminal.
 
 RabbitMQ
+
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env --profile infrastructure --profile frontend up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env --profile infrastructure --profile frontend up -d
 ```
+
 Azure Service Bus
+
+See [ASB setup](#alternative-run-from-azure-service-bus) above for setting the connection string to your Azure Service Bus namespace
+
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env --profile infrastructure --profile frontend up -d
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env --profile infrastructure --profile frontend up -d
 ```
 
 After opening the solution (from Visual Studio or Rider), choose one of the run profiles that matches the transport configured previously:
@@ -56,6 +64,53 @@ After opening the solution (from Visual Studio or Rider), choose one of the run
 
 Run the solution to start the demo.
 
+</details>
+
 ## Opening the showcase UI
 
-Navigate to http://localhost:61335/ to see the UI.
+Navigate to http://localhost:61335/ to see the UI. Click `Run Scenario` to start the showcase scenario and generate some simulated message handling failures.
+
+## Handling failures with the Particular Platform
+
+### Inspecting failures
+
+Navigate to [http://localhost:9090](http://localhost:9090) in a new tab, or click the `View in ServicePulse` button, to see the details on failures ingested by the platform.
+
+![Service Pulse Dashboard](docs/service-pulse-dashboard-failed-messages.png "Message processing errors summary view")
+
+### Scheduling message reprocessing
+
+Click on the "Failed Messages" button at the top of the page to see all failed messages ingested by the platform, grouped by the exception type and stack trace.
+
+![Service Pulse Failed Messages](docs/service-pulse-dashboard-failed-messages-groups.png "Failed messages grouping")
+
+Drill into an existing group to see the list of individual processing failures. Clicking on any of the rows in the list shows detailed information of a given failed message in the headers and message body tabs.
+
+A failed message can be scheduled for reprocessing by clicking the `Retry message` button.
+
+> [!NOTE]
+> It may take several seconds after retrying a message for it to appear again in the consumer's input queue
+
+![Service Pulse Failed Message View](docs/service-pulse-failed-message-view.png "Failed message details view")
+
+### Editing messages before reprocessing
+
+Go to the details page for one of the failed messages and click the `Edit & retry` button. The pop-up window shows the headers collection and the message body in two separate tabs.
+
+Navigate to the `Message Body` tab and change some of the contents of the message, ensuring it's still valid JSON matching the message type, and click "Retry" to schedule the message for reprocessing.
+
+> [!WARNING]
+> Changing or deleting header values may change or cause issues with the subsequent re-processing. It is recommended that these values are not changed if you are unsure of their purpose.
+
+![Edit Message View](docs/service-pulse-edit-before-retry.png "Edit & Retry view showing the message body")
+
+### Viewing retries
+
+Return to the showcase UI to see that the retries have now been successfully handled.
+
+### Troubleshooting
+
+Having issues?
+
+- Check logs in docker. Ensure that there are no port clashes with existing containers or services on your machine.
+- Ask any questions on [our forum](https://discuss.particular.net/tag/masstransit)

src/compose-rabbitmq-user.yml

@@ -0,0 +1,11 @@
+services:
+  masstransit-connector:
+    environment:
+      - RABBITMQ_MANAGEMENT_API_URL
+      - RABBITMQ_MANAGEMENT_API_USERNAME
+      - RABBITMQ_MANAGEMENT_API_PASSWORD
+  service-control:
+    environment:
+      - LICENSINGCOMPONENT_RABBITMQ_APIURL=${RABBITMQ_MANAGEMENT_API_URL}
+      - LICENSINGCOMPONENT_RABBITMQ_USERNAME=${RABBITMQ_MANAGEMENT_API_USERNAME}
+      - LICENSINGCOMPONENT_RABBITMQ_PASSWORD=${RABBITMQ_MANAGEMENT_API_PASSWORD}

src/compose-rabbitmq.yml

@@ -21,7 +21,7 @@ services:
       - rabbitmq-logs:/var/log/rabbitmq
     ports:
       - 33721:5672
-      - 15672:15672     
+      - 33672:15672     
     configs:
       - source: plugins
         target: /etc/rabbitmq/enabled_plugins
@@ -30,6 +30,10 @@ services:
     depends_on:
       rabbitmq:
         condition: service_healthy
+    environment:
+      - LICENSINGCOMPONENT_RABBITMQ_APIURL=${RABBITMQ_MANAGEMENT_API_URL}
+      - LICENSINGCOMPONENT_RABBITMQ_USERNAME=${RABBITMQ_MANAGEMENT_API_USERNAME}
+      - LICENSINGCOMPONENT_RABBITMQ_PASSWORD=${RABBITMQ_MANAGEMENT_API_PASSWORD}
 
   masstransit-connector:
     environment:

src/frontend/public/azure.md

@@ -7,6 +7,6 @@
 3. Open a terminal and run these commands:
 
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env down
-docker compose -f docker-compose-base.yml --env-file asb.env --profile infrastructure up
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-azure.yml --env-file asb.env down
+docker compose -p particular-platform -f docker-compose-base.yml --env-file asb.env --profile infrastructure up
 ```

src/frontend/public/rabbit.md

@@ -1,14 +1,14 @@
 # Running with your own RabbitMQ system
 
 1. Open the `src/rabbit.env` file in an editor and update the RabbitMQ configuration to point to your own RabbitMQ instance.
-   1. `CONNECTION_STRING` A special connection string to connect to RabbtiMQ, see https://docs.particular.net/servicecontrol/transports#rabbitmq for syntax format.
+   1. `CONNECTION_STRING` A special connection string to connect to RabbitMQ, see https://docs.particular.net/servicecontrol/transports#rabbitmq for syntax format.
    2. `RABBITMQ_MANAGEMENT_API_URL` The management API URL.
    3. `RABBITMQ_MANAGEMENT_API_USERNAME` The management API username.
    4. `RABBITMQ_MANAGEMENT_API_PASSWORD` The management API password.
 2. Update the list of queues you want to monitor by editing the `src/queues.txt` file. RabbitMQ is case-sensitive so make sure the names are exact. e.g. `myqueue_error`.
 3. Open a terminal and run these commands:
 
 ```cmd
-docker compose -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env down
-docker compose -f docker-compose-base.yml --env-file rabbit.env --profile infrastructure up
+docker compose -p particular-platform-showcase -f docker-compose-base.yml -f compose-rabbitmq.yml --env-file rabbit.env down
+docker compose -p particular-platform -f docker-compose-base.yml -f compose-rabbitmq-user.yml --env-file rabbit.env --profile infrastructure up
 ```

src/frontend/src/components/guideline/TryItOut.vue

@@ -89,5 +89,6 @@ onMounted(async () => {
   margin: 0.5em;
   padding-left: 1em;
   background-color: lightgray;
+  overflow: auto;
 }
 </style>

src/rabbit.env

@@ -5,3 +5,8 @@ CONNECTION_STRING="host=rabbitmq"
 RABBITMQ_MANAGEMENT_API_URL="http://rabbitmq:15672"
 RABBITMQ_MANAGEMENT_API_USERNAME=guest
 RABBITMQ_MANAGEMENT_API_PASSWORD=guest
+
+#Only used for the showcase processes
+RABBITMQ_HOST="rabbitmq"
+RABBITMQ_PORT="5672"
+RABBITMQ_VIRTUALHOST="/"