feat: better documentation clarity across cadence-samples to reduce onboarding friction for new developers

README.md

@@ -38,6 +38,46 @@ This downloads and starts all required dependencies including Cadence server, da
 make
 ```
 
+### Docker Troubleshooting
+
+The `docker-compose` command requires Docker daemon to be running. On macOS/Windows, open Docker Desktop. On Linux, run `sudo systemctl start docker`.
+
+<details>
+<summary>Port conflicts</summary>
+
+If you see `Bind for 0.0.0.0:<port> failed: port is already allocated`, find the process using that port:
+
+```bash
+lsof -i tcp:<port>
+```
+
+To find which container is using it:
+```bash
+docker ps --format '{{.ID}}\t{{.Ports}}\t{{.Names}}' | grep <port>
+```
+
+Stop and remove the conflicting container:
+```bash
+docker stop <container_id> && docker rm <container_id>
+```
+
+Cadence uses these ports: `7833`, `7933`, `7939`, `8000-8003`, `8088` (Web UI), `9042` (Cassandra), `9090` (Prometheus), `3000` (Grafana).
+
+</details>
+
+<details>
+<summary>Reset everything</summary>
+
+```bash
+docker-compose down
+docker ps -a  # check for leftover containers
+docker rm <container_id>  # remove if needed
+```
+
+Verify with `docker ps` and visit [http://localhost:8088](http://localhost:8088).
+
+</details>
+
 ## 📚 Sample Categories
 
 ### Table of Contents

config/development.yaml

@@ -1,5 +1,5 @@
 # config for sample
-domain: "default"
+domain: "cadence-samples"
 service: "cadence-frontend"
 host: "localhost:7833"
 # config for emitting metrics

new_samples/README.md

@@ -33,43 +33,41 @@ cadence --env development \
 Try to inspect the log message for the output.
 
 ### Signal Workflow
-This workflow demonstrate a basic signal workflow. It takes your name as input parameter
-and greet you based on languages you pick. To start the workflow, try the following CLI.
+This workflow demonstrates a basic signal workflow. It waits for a signal to complete.
+To start the workflow, try the following CLI.
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
   workflow start \
-  --workflow_type cadence_samples.SignalGreeterMultiLanguageWorkflow \
+  --workflow_type cadence_samples.SimpleSignalWorkflow \
   --tl cadence-samples-worker \
-  --et 6000 \
-  --input '{"name":"Uber"}'
+  --et 600
 ```
 
-A workflow ID and run ID will be return in your terminal. Copy the workflow ID and replace
-to the CLI below to trigger the signal. Try to change the input language value and inspect what
-happens in the log. Also, try to inspect what happened after you interact with the signal multiple times.
+A workflow ID and run ID will be returned in your terminal. Copy the workflow ID and use
+the CLI below to send a signal. The workflow will continue running until it receives a
+`complete` signal with the value `true`.
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
   workflow signal \
-  --workflow_id <Your workflow ID> \
-  --name "language" \
-  --input '"english"'
+  --wid <Your workflow ID> \
+  --name "complete" \
+  --input 'false'
 ```
 
-To cancel the workflow, try the following CLI.
+To complete the workflow, send the signal with `true`:
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
   workflow signal \
-  --workflow_id <Your workflow ID> \
-  --name "cancel" \
+  --wid <Your workflow ID> \
+  --name "complete" \
   --input 'true'
 ```
-The workflow should have a status of fail.
 
 ### Dynamic workflow
 This dynamic workflow is very similar to the Hello World workflow above, but instead of passing the

new_samples/hello_world/README.md

@@ -43,6 +43,14 @@ cadence --env development \
   --input '{"message":"Cadence"}'
 ```
 
+You should see output like this:
+
+![Trigger command output](images/02-trigger-command-started-workflow.png)
+
+And the worker will log the completed workflow:
+
+![Worker output showing workflow completed](images/01-worker-output-workflow-completed.png)
+
 Here are the details to this command:
 
 * `--domain` option describes under which domain to run this workflow
@@ -60,24 +68,33 @@ To see more options run `cadence --help`
 
 Click on `cadence-samples` domain in cadence-web to view your workflow.
 
+![Workflow list showing completed workflow](images/03-web-ui-workflow-list-completed.png)
+
+Click on the workflow to see details:
+
 * In Summary tab, you will see the input and output to your workflow
-* Click on History tab to see individual steps.
+
+![Summary tab](images/04-web-ui-summary-tab.png)
+
+* Click on History tab to see individual steps. Expand an activity to see its result:
+
+![History tab with activity result](images/05-web-ui-history-activity-result.png)
 
 #### CLI
 
 List workflows using the following command:
 
 ```bash
- cadence --env development --domain cadence-samples --workflow list
+cadence --env development --domain cadence-samples workflow list
 ```
 
 You can view an individual workflow by using the following command:
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow describe \
- --wid <workflow_id>
+  workflow describe \
+  --wid <workflow_id>
 ```
 
 * `workflow` is the noun to run commands within workflow scope
@@ -90,10 +107,18 @@ To view the entire history of the workflow, use the following command:
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow show \
- --wid <workflow_id>
+  workflow show \
+  --wid <workflow_id>
 ```
 
+## Troubleshooting
+
+If you see port conflicts when starting Docker, use `lsof` to find what's using the port:
+
+![Docker port conflict troubleshooting](images/06-docker-port-conflict-troubleshooting.png)
+
+See the main [README](../../README.md#docker-troubleshooting) for detailed Docker troubleshooting steps.
+
 ## References
 
 * The website: https://cadenceworkflow.io

new_samples/hello_world/generator/README_specific.md

@@ -37,16 +37,16 @@ Click on `cadence-samples` domain in cadence-web to view your workflow.
 List workflows using the following command:
 
 ```bash
- cadence --env development --domain cadence-samples --workflow list
+cadence --env development --domain cadence-samples workflow list
 ```
 
 You can view an individual workflow by using the following command:
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow describe \
- --wid <workflow_id>
+  workflow describe \
+  --wid <workflow_id>
 ```
 
 * `workflow` is the noun to run commands within workflow scope
@@ -59,6 +59,6 @@ To view the entire history of the workflow, use the following command:
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow show \
- --wid <workflow_id>
+  workflow show \
+  --wid <workflow_id>
 ```

new_samples/worker/worker.go

@@ -46,8 +46,8 @@ func StartWorker() {
 	w.RegisterActivityWithOptions(workflows.HelloWorldActivity, activity.RegisterOptions{Name: "cadence_samples.HelloWorldActivity"})
 
 	// Signal workflow registration
-	w.RegisterWorkflowWithOptions(workflows.SignalGreeterMultiLanguageWorkflow, workflow.RegisterOptions{Name: "cadence_samples.SignalGreeterMultiLanguageWorkflow"})
-	w.RegisterActivityWithOptions(workflows.GenerateGreetingMessage, activity.RegisterOptions{Name: "cadence_samples.GenerateGreetingMessage"})
+	w.RegisterWorkflowWithOptions(workflows.SimpleSignalWorkflow, workflow.RegisterOptions{Name: "cadence_samples.SimpleSignalWorkflow"})
+	w.RegisterActivityWithOptions(workflows.SimpleSignalActivity, activity.RegisterOptions{Name: "cadence_samples.SimpleSignalActivity"})
 
 	// Dynamic workflow registration
 	w.RegisterWorkflowWithOptions(workflows.DynamicWorkflow, workflow.RegisterOptions{Name: "cadence_samples.DynamicWorkflow"})

new_samples/workflows/simple_signal_workflow.go

@@ -0,0 +1,60 @@
+package workflows
+
+import (
+	"context"
+	"strconv"
+	"time"
+
+	"go.uber.org/cadence/activity"
+	"go.uber.org/cadence/workflow"
+	"go.uber.org/zap"
+)
+
+const (
+	CompleteSignalChan = "complete"
+)
+
+// SimpleSignalWorkflow demonstrates a basic signal workflow.
+// It waits for a "complete" signal to finish.
+func SimpleSignalWorkflow(ctx workflow.Context) error {
+	ao := workflow.ActivityOptions{
+		ScheduleToStartTimeout: time.Minute * 60,
+		StartToCloseTimeout:    time.Minute * 60,
+	}
+	ctx = workflow.WithActivityOptions(ctx, ao)
+	logger := workflow.GetLogger(ctx)
+	logger.Info("SimpleSignalWorkflow started")
+
+	var complete bool
+	completeChan := workflow.GetSignalChannel(ctx, CompleteSignalChan)
+	for {
+		s := workflow.NewSelector(ctx)
+		s.AddReceive(completeChan, func(ch workflow.Channel, ok bool) {
+			if ok {
+				ch.Receive(ctx, &complete)
+			}
+			logger.Info("Signal input: " + strconv.FormatBool(complete))
+		})
+		s.Select(ctx)
+
+		var result string
+		err := workflow.ExecuteActivity(ctx, SimpleSignalActivity, complete).Get(ctx, &result)
+		if err != nil {
+			return err
+		}
+		logger.Info("Activity result: " + result)
+		if complete {
+			return nil
+		}
+	}
+}
+
+// SimpleSignalActivity logs the signal received and returns a status message.
+func SimpleSignalActivity(ctx context.Context, complete bool) (string, error) {
+	logger := activity.GetLogger(ctx)
+	logger.Info("SimpleSignalActivity started, a new signal has been received", zap.Bool("complete", complete))
+	if complete {
+		return "Workflow will complete now", nil
+	}
+	return "Workflow will continue to run", nil
+}