diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md new file mode 100644 index 00000000000..27dc31fc2b1 --- /dev/null +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-and-handle-triggered-jobs.md @@ -0,0 +1,149 @@ +--- +type: docs +title: "How-To: Schedule and handle triggered jobs" +linkTitle: "How-To: Schedule and handle triggered jobs" +weight: 2000 +description: "Learn how to use the jobs API to schedule and handle triggered jobs" +--- + +Now that you've learned what the [jobs building block]({{< ref jobs-overview.md >}}) provides, let's look at an example of how to use the API. The code example below describes an application that schedules jobs for a database backup application and handles them at trigger time, also known as the time the job was sent back to the application because it reached it's dueTime. + + + +## Start the Scheduler service + +When you [run `dapr init` in either self-hosted mode or on Kubernetes]({{< ref install-dapr-selfhost.md >}}), the Dapr Scheduler service is started. + +## Set up the Jobs API + +In your code, set up and schedule jobs within your application. + +{{< tabs "Go" >}} + +{{% codetab %}} + + + +The following Go SDK code sample schedules the job named `prod-db-backup`. Job data is housed in a backup database (`"my-prod-db"`) and is scheduled with `ScheduleJobAlpha1`. This provides the `jobData`, which includes: +- The backup `Task` name +- The backup task's `Metadata`, including: + - The database name (`DBName`) + - The database location (`BackupLocation`) + + +```go +package main + +import ( + //... + + daprc "github.com/dapr/go-sdk/client" + "github.com/dapr/go-sdk/examples/dist-scheduler/api" + "github.com/dapr/go-sdk/service/common" + daprs "github.com/dapr/go-sdk/service/grpc" +) + +func main() { + // Initialize the server + server, err := daprs.NewService(":50070") + // ... + + if err = server.AddJobEventHandler("prod-db-backup", prodDBBackupHandler); err != nil { + log.Fatalf("failed to register job event handler: %v", err) + } + + log.Println("starting server") + go func() { + if err = server.Start(); err != nil { + log.Fatalf("failed to start server: %v", err) + } + }() + // ... + + // Set up backup location + jobData, err := json.Marshal(&api.DBBackup{ + Task: "db-backup", + Metadata: api.Metadata{ + DBName: "my-prod-db", + BackupLocation: "/backup-dir", + }, + }, + ) + // ... +} +``` + +The job is scheduled with a `Schedule` set and the amount of `Repeats` desired. These settings determine a max amount of times the job should be triggered and sent back to the app. + +In this example, at trigger time, which is `@every 1s` according to the `Schedule`, this job is triggered and sent back to the application up to the max `Repeats` (`10`). + +```go + // ... + // Set up the job + job := daprc.Job{ + Name: "prod-db-backup", + Schedule: "@every 1s", + Repeats: 10, + Data: &anypb.Any{ + Value: jobData, + }, + } +``` + +At the trigger time, the `prodDBBackupHandler` function is called, executing the desired business logic for this job at trigger time. For example: + +```go +// ... + +// At job trigger time this function is called +func prodDBBackupHandler(ctx context.Context, job *common.JobEvent) error { + var jobData common.Job + if err := json.Unmarshal(job.Data, &jobData); err != nil { + // ... + } + decodedPayload, err := base64.StdEncoding.DecodeString(jobData.Value) + // ... + + var jobPayload api.DBBackup + if err := json.Unmarshal(decodedPayload, &jobPayload); err != nil { + // ... + } + fmt.Printf("job %d received:\n type: %v \n typeurl: %v\n value: %v\n extracted payload: %v\n", jobCount, job.JobType, jobData.TypeURL, jobData.Value, jobPayload) + jobCount++ + return nil +} +``` + +{{% /codetab %}} + +{{< /tabs >}} + +## Run the Dapr sidecar + +Once you've set up the Jobs API in your application, in a terminal window run the Dapr sidecar with the following command. + +{{< tabs "Go" >}} + +{{% codetab %}} + +```bash +dapr run --app-id=distributed-scheduler \ + --metrics-port=9091 \ + --dapr-grpc-port 50001 \ + --app-port 50070 \ + --app-protocol grpc \ + --log-level debug \ + go run ./main.go +``` + +{{% /codetab %}} + +{{< /tabs >}} + + +## Next steps + +- [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}}) +- [Jobs API reference]({{< ref jobs_api.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-jobs.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-jobs.md deleted file mode 100644 index fb4263ef184..00000000000 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/howto-schedule-jobs.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -type: docs -title: "How-To: Schedule jobs" -linkTitle: "How-To: Schedule jobs" -weight: 2000 -description: "Learn how to use the jobs API to schedule jobs" ---- - -Now that you've learned what the [jobs building block]({{< ref jobs-overview.md >}}) provides, let's look at an example of how to use the API. The code example below describes an application that schedules jobs for a **TBD** application. - - - -## Set up the Scheduler service - -{{% alert title="Warning" color="warning" %}} -By default, job data is not resilient to [Scheduler]({{< ref scheduler.md >}}) service restarts. -A persistent volume must be provided to Scheduler to ensure job data is not lost in either [Kubernetes]({{< ref kubernetes-persisting-scheduler.md >}}) or [Self-Hosted]({{< ref self-hosted-persisting-scheduler.md >}}) mode. -{{% /alert %}} - -When you run `dapr init` in either self-hosted mode or on Kubernetes, the Dapr scheduler service is started. - -## Run the Dapr sidecar - -Run the Dapr sidecar alongside your application. - -```bash -dapr run --app-id=jobs --app-port 50070 --app-protocol grpc --log-level debug -- go run main.go -``` - -## Next steps - -- [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}}) -- [Jobs API reference]({{< ref jobs_api.md >}}) diff --git a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md index a7838088d59..b4d5214ebcf 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/jobs/jobs-overview.md @@ -70,10 +70,10 @@ Actors have actor reminders, but present some limitations involving scalability ## Try out the jobs API -You can try out the jobs API in your application. After [Dapr is installed]({{< ref install-dapr-cli.md >}}), you can begin using the jobs API, starting with [the How-to: Schedule jobs guide]({{< ref howto-schedule-jobs.md >}}). +You can try out the jobs API in your application. After [Dapr is installed]({{< ref install-dapr-cli.md >}}), you can begin using the jobs API, starting with [the How-to: Schedule jobs guide]({{< ref howto-schedule-and-handle-triggered-jobs.md >}}). ## Next steps -- [Learn how to use the jobs API]({{< ref howto-schedule-jobs.md >}}) +- [Learn how to use the jobs API]({{< ref howto-schedule-and-handle-triggered-jobs.md >}}) - [Learn more about the Scheduler control plane service]({{< ref "concepts/dapr-services/scheduler.md" >}}) - [Jobs API reference]({{< ref jobs_api.md >}}) diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index fc82e73ca5a..b851a3c25db 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -95,28 +95,11 @@ dapr init **Expected output:** -``` -⌛ Making the jump to hyperspace... -✅ Downloaded binaries and completed components set up. -ℹ️ daprd binary has been installed to $HOME/.dapr/bin. -ℹ️ dapr_placement container is running. -ℹ️ dapr_scheduler container is running. -ℹ️ dapr_redis container is running. -ℹ️ dapr_zipkin container is running. -ℹ️ Use `docker ps` to check running containers. -✅ Success! Dapr is up and running. To get started, go here: https://aka.ms/dapr-getting-started -``` + [See the troubleshooting guide if you encounter any error messages regarding Docker not being installed or running.]({{< ref "common_issues.md#dapr-cant-connect-to-docker-when-installing-the-dapr-cli" >}}) -#### Slim init - -To install the CLI without any default configuration files or Docker containers, use the `--slim` flag. [Learn more about the `init` command and its flags.]({{< ref dapr-init.md >}}) - -```bash -dapr init --slim -``` - ### Step 3: Verify Dapr version ```bash @@ -138,7 +121,7 @@ docker ps **Output:** - + ### Step 5: Verify components directory has been initialized @@ -189,5 +172,14 @@ explorer "%USERPROFILE%\.dapr"
+### Slim init + +To install the CLI without any default configuration files or Docker containers, use the `--slim` flag. [Learn more about the `init` command and its flags.]({{< ref dapr-init.md >}}) + +```bash +dapr init --slim +``` + + {{< button text="Next step: Use the Dapr API >>" page="getting-started/get-started-api.md" >}} diff --git a/daprdocs/content/en/reference/cli/dapr-uninstall.md b/daprdocs/content/en/reference/cli/dapr-uninstall.md index cf9091c04af..8779878206a 100644 --- a/daprdocs/content/en/reference/cli/dapr-uninstall.md +++ b/daprdocs/content/en/reference/cli/dapr-uninstall.md @@ -24,10 +24,10 @@ dapr uninstall [flags] | Name | Environment Variable | Default | Description | | -------------------- | -------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--all` | | `false` | Remove Redis, Zipkin containers in addition to the scheduler service and the actor placement container. Remove default dapr dir located at `$HOME/.dapr or %USERPROFILE%\.dapr\`. | +| `--all` | | `false` | Remove Redis, Zipkin containers in addition to the Scheduler service and the actor Placement service containers. Remove default Dapr dir located at `$HOME/.dapr or %USERPROFILE%\.dapr\`. | | `--help`, `-h` | | | Print this help message | | `--kubernetes`, `-k` | | `false` | Uninstall Dapr from a Kubernetes cluster | -| `--namespace`, `-n` | | `dapr-system` | The Kubernetes namespace to uninstall Dapr from | +| `--namespace`, `-n` | | `dapr-system` | The Kubernetes namespace from which Dapr is uninstalled | | `--container-runtime` | | `docker` | Used to pass in a different container runtime other than Docker. Supported container runtimes are: `docker`, `podman` | ### Examples diff --git a/daprdocs/static/images/install-dapr-selfhost/dapr-init-output.png b/daprdocs/static/images/install-dapr-selfhost/dapr-init-output.png new file mode 100644 index 00000000000..61018d15027 Binary files /dev/null and b/daprdocs/static/images/install-dapr-selfhost/dapr-init-output.png differ diff --git a/daprdocs/static/images/install-dapr-selfhost/docker-containers.png b/daprdocs/static/images/install-dapr-selfhost/docker-containers.png index d9300e2ac94..377c6a313dc 100644 Binary files a/daprdocs/static/images/install-dapr-selfhost/docker-containers.png and b/daprdocs/static/images/install-dapr-selfhost/docker-containers.png differ