diff --git a/daprdocs/content/en/getting-started/_index.md b/daprdocs/content/en/getting-started/_index.md index dc2fa38aa..bfcf1a98f 100644 --- a/daprdocs/content/en/getting-started/_index.md +++ b/daprdocs/content/en/getting-started/_index.md @@ -3,17 +3,17 @@ type: docs title: "Getting started with Dapr" linkTitle: "Getting started" weight: 20 -description: "Get up and running with Dapr" +description: "How to get up and running with Dapr in minutes" no_list: true --- Welcome to the Dapr getting started guide! {{% alert title="Dapr Concepts" color="primary" %}} -If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}) in the docs. +If you are looking for an introductory overview of Dapr and learn more about basic Dapr terminology, it is recommended to visit the [concepts section]({{}}). {{% /alert %}} -This guide will walk you through a series of steps to install, initialize and start using Dapr. The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}}) which includes the Dapr CLI and Dapr sidecar binaries as well as some default components that can help you start using Dapr quickly. +This guide will walk you through a series of steps to install, initialize and start using Dapr. The recommended way to get started with Dapr is to setup a local development environment (also referred to as [_self-hosted_ mode]({{< ref self-hosted >}})) which includes the Dapr CLI, Dapr sidecar binaries, and some default components that can help you start using Dapr quickly. The following steps in this guide are: 1. Install the Dapr CLI @@ -22,5 +22,5 @@ The following steps in this guide are: 1. Configure a component 1. Explore Dapr quickstarts -Next step: Install the Dapr CLI >> +First step: Install the Dapr CLI >> diff --git a/daprdocs/content/en/getting-started/get-started-api.md b/daprdocs/content/en/getting-started/get-started-api.md index eb4d1f650..ef3c7f075 100644 --- a/daprdocs/content/en/getting-started/get-started-api.md +++ b/daprdocs/content/en/getting-started/get-started-api.md @@ -5,27 +5,21 @@ linkTitle: "Use the Dapr API" weight: 30 --- -After running the `dapr init` command in the previous step, your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. - -The way it works is depicted in the illustration below: - - - -The illustration shows how an application calls the Dapr sidecar using the state API. In turn, the sidecar calls a state store component (in this case the local Redis container that was set up in the previous step) to get and set a state. +After running the `dapr init` command in the previous step, your local environment has the Dapr sidecar binaries as well as default component definitions for both state management and a message broker (both using Redis). You can now try out some of what Dapr has to offer by using the Dapr CLI to run a Dapr sidecar and try out the state API that will allow you to store and retrieve a state. You can learn more about the state building block and how it works in [these docs]({{< ref state-management >}}). You will now run the sidecar and call the API directly (simulating what an application would do). -### Run the Dapr sidecar +### Step 1: Run the Dapr sidecar -One the most useful Dapr CLI commands is `dapr run`. This command launches an application together with a sidecar. For the purpose of this tutorial, you'll run the sidecar without an application (see the [CLI reference]({{}}) for usage of `dapr run` and more information). +One the most useful Dapr CLI commands is [`dapr run`]({{< ref dapr-run.md >}}). This command launches an application together with a sidecar. For the purpose of this tutorial you'll run the sidecar without an application. -Run the following command to run the Dapr sidecar, indicating it is listening on port 3500 and providing an app-id. +Run the following command to launch a Dapr sidecar that will listen on port 3500 for a blank application named myapp: ```bash dapr run --app-id myapp --dapr-http-port 3500 ``` -### Set a state +### Step 2: Save state In a separate terminal run: @@ -46,21 +40,21 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '[{ "key": {{< /tabs >}} -### Get a state +### Step 2: Get state Now get the state you just stored using a key with the state management API: {{< tabs "HTTP API (Bash)" "HTTP API (PowerShell)">}} {{% codetab %}} -With the same dapr instance running from above run: +With the same Dapr instance running from above run: ```bash curl http://localhost:3500/v1.0/state/statestore/name ``` {{% /codetab %}} {{% codetab %}} -With the same dapr instance running from above run: +With the same Dapr instance running from above run: ```powershell Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name' ``` @@ -68,7 +62,7 @@ Invoke-RestMethod -Uri 'http://localhost:3500/v1.0/state/statestore/name' {{< /tabs >}} -### See how the state is stored in Redis +### Step 3: See how the state is stored in Redis You can look in the Redis container and verify Dapr is using it as a state store. Run the following to use the Redis CLI: @@ -76,7 +70,7 @@ You can look in the Redis container and verify Dapr is using it as a state store docker exec -it dapr_redis redis-cli ``` -And then see how Dapr created a key value pair (with the app-id you provided to `dapr run` as a prefix to the key): +List the redis keys to see how Dapr created a key value pair (with the app-id you provided to `dapr run` as a prefix to the key): ```bash keys * @@ -86,6 +80,7 @@ keys * 1) "myapp||name" ``` +View the state value by running: ```bash hgetall "myapp||name" @@ -98,6 +93,8 @@ hgetall "myapp||name" 4) "1" ``` +Exit the redis-cli with: + ```bash exit ``` diff --git a/daprdocs/content/en/getting-started/install-dapr-cli.md b/daprdocs/content/en/getting-started/install-dapr-cli.md index dba84713c..de3ecf74e 100644 --- a/daprdocs/content/en/getting-started/install-dapr-cli.md +++ b/daprdocs/content/en/getting-started/install-dapr-cli.md @@ -5,11 +5,11 @@ linkTitle: "Install Dapr CLI" weight: 10 --- -The Dapr CLI is main tool you'll be using for various Dapr related tasks. Most importantly it is used to run an application with a Dapr sidecar, but it also can review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. +The Dapr CLI is the main tool you'll be using for various Dapr related tasks. You can use it to run an application with a Dapr sidecar, as well as review sidecar logs, list running services, and run the Dapr dashboard. The Dapr CLI works with both [self-hosted]({{< ref self-hosted >}}) and [Kubernetes]({{< ref Kubernetes >}}) environments. -Learn more about the CLI and available commands in the [CLI reference docs]( {{< ref cli >}}). +You can learn more about the CLI and available commands in the [CLI reference docs]( {{< ref cli >}}). -### Run the installation script +### Step 1: Run the installation script Begin by downloading and installing the latest version of the Dapr CLI: @@ -27,11 +27,10 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O {{% /codetab %}} {{% codetab %}} -This command installs the latest windows Dapr cli to `C:\dapr` and add this directory to User PATH environment variable. Run in Command Prompt: +This Command Prompt command installs the latest windows Dapr cli to `C:\dapr` and adds this directory to User PATH environment variable. ```powershell powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex" ``` -Verify by opening Explorer and entering `C:\dapr` into the address bar. You should see folders for bin, components, and a config file. {{% /codetab %}} {{% codetab %}} @@ -53,14 +52,14 @@ Each release of Dapr CLI includes various OSes and architectures. These binary v 2. Unpack it (e.g. dapr_linux_amd64.tar.gz, dapr_windows_amd64.zip) 3. Move it to your desired location. - For Linux/MacOS - `/usr/local/bin` - - For Windows, create a directory and add this to your System PATH. For example create a directory called `c:\dapr` and add this directory to your path, by editing your system environment variable. + - For Windows, create a directory and add this to your System PATH. For example create a directory called `C:\dapr` and add this directory to your User PATH, by editing your system environment variable. {{% /codetab %}} {{< /tabs >}} -### Verify the installation +### Step 2: Verify the installation -You can verify the CLI is installed by running the following: +You can verify the CLI is installed by restarting your terminal/command prompt and running the following: ```bash dapr @@ -69,7 +68,7 @@ dapr The output should look like this: -```bash +```md ____/ /___ _____ _____ / __ / __ '/ __ \/ ___/ diff --git a/daprdocs/content/en/getting-started/install-dapr-selfhost.md b/daprdocs/content/en/getting-started/install-dapr-selfhost.md index 0cc333282..3df674abf 100644 --- a/daprdocs/content/en/getting-started/install-dapr-selfhost.md +++ b/daprdocs/content/en/getting-started/install-dapr-selfhost.md @@ -7,40 +7,40 @@ aliases: - /getting-started/install-dapr/ --- -{{% alert title="Note" color="warning" %}} -This page provides instructions for installing Dapr runtime v0.11. To install v1.0-rc2 preview, the release candidate for the upcoming v1.0 release please visit the [v1.0-rc2 docs version of this page](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-selfhost/). Note you will need to ensure you are also using the preview version of the CLI (instructions to install the latest preview CLI can be found [here](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/)). -{{% /alert %}} - Now that you have the Dapr CLI installed, it's time to initialize Dapr on your local machine using the CLI. -Dapr runs as a sidecar alongside your application, and in self-hosted mode this means as a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally. +Dapr runs as a sidecar alongside your application, and in self-hosted mode this means it is a process on your local machine. Therefore, initializing Dapr includes fetching the Dapr sidecar binaries and installing them locally. -In addition, the default initialization process also creates a development environment that helps streamlining application development with Dapr. This includes the following steps: +In addition, the default initialization process also creates a development environment that helps streamline application development with Dapr. This includes the following steps: + +1. Running a **Redis container instance** to be used as a local state store and message broker +1. Running a **Zipkin container instance** for observability +1. Creating a **default components folder** with component definitions for the above +1. Running a **Dapr placement service container instance** for local actor support + +{{% alert title="Dapr release candidate" color="warning" %}} +This page provides instructions for installing Dapr runtime v0.11. To install v1.0-rc2 preview, the release candidate for the upcoming v1.0 release please visit the [v1.0-rc2 docs version of this page](https://v1-rc1.docs.dapr.io/getting-started/install-dapr-selfhost/). Note you will need to ensure you are also using the preview version of the CLI (instructions to install the latest preview CLI can be found [here](https://v1-rc2.docs.dapr.io/getting-started/install-dapr-cli/)). +{{% /alert %}} {{% alert title="Docker" color="primary" %}} This recommended development environment requires [Docker](https://docs.docker.com/install/). It is possible to initialize Dapr without a dependency on Docker (see [this guidance]({{}})) but next steps in this guide assume the recommended development environment. {{% /alert %}} -1. Running a Redis container instance to be used as a local state store and message broker -1. Running a Zipkin container instance for observability -1. Creating a default components folder with component definitions for the above -1. Running a container with a Dapr placement service for local actors - -### Ensure you are in an elevated terminal +### Step 1: Open an elevated terminal {{< tabs "Linux/MacOS" "Windows">}} {{% codetab %}} - If you run your docker commands with sudo or the install path is `/usr/local/bin`(default install path), you need to use `sudo` + If you run your Docker commands with sudo, or the install path is `/usr/local/bin` (default install path), you will need to use `sudo` below. {{% /codetab %}} {{% codetab %}} - Make sure that you run the command prompt terminal in administrator mode (right click, run as administrator) + Make sure that you run Command Prompt as administrator (right click, run as administrator) {{% /codetab %}} {{< /tabs >}} -### Run the init CLI command +### Step 2: Run the init CLI command Install the latest Dapr runtime binaries: @@ -48,10 +48,7 @@ Install the latest Dapr runtime binaries: dapr init ``` -Instead of the latest Dapr binaries, you can install or upgrade to a specific version of the Dapr runtime using `dapr init --runtime-version`. You can find the list of versions in [Dapr Release](https://github.com/dapr/dapr/releases) - - -### Verify Dapr version +### Step 3: Verify Dapr version ```bash dapr --version @@ -63,12 +60,12 @@ CLI version: 0.11 Runtime version: 0.11 ``` -### Verify containers are running +### Step 4: Verify containers are running As mentioned above, the `dapr init` command launches several containers that will help you get started with Dapr. Verify this by running: ```bash - docker ps +docker ps ``` Make sure that instances with `daprio/dapr`, `openzipkin/zipkin`, and `redis` images are all running: @@ -80,9 +77,9 @@ CONTAINER ID IMAGE COMMAND CREATED 8d993e514150 daprio/dapr "./placement" 2 minutes ago Up 2 minutes 0.0.0.0:6050->50005/tcp dapr_placement ``` -### Verify components directory has been initialized +### Step 5: Verify components directory has been initialized -On init, the CLI also creates a default components folder which includes several YAML files with definitions for a state store, pub/sub and zipkin. These will be read by the Dapr sidecar, telling it to use the Redis container for state management and messaging and the Zipkin container for collecting traces. +On `dapr init`, the CLI also creates a default components folder which includes several YAML files with definitions for a state store, pub/sub and zipkin. These will be read by the Dapr sidecar, telling it to use the Redis container for state management and messaging and the Zipkin container for collecting traces. - In Linux/MacOS Dapr is initialized with default components and files in `$HOME/.dapr`. - For Windows Dapr is initialized to `%USERPROFILE%\.dapr\` @@ -95,17 +92,21 @@ Run: ```bash ls $HOME/.dapr ``` -Output should look like so: +You should see: ``` bin components config.yaml ``` {{% /codetab %}} {{% codetab %}} -Open `%USERPROFILE%\.dapr\` in file explorer +Open `%USERPROFILE%\.dapr\` in file explorer: + +```powershell +explorer "%USERPROFILE%\.dapr\" +``` -![Explorer files](/images/install-dapr-selfhost-windows.png) + {{% /codetab %}} {{< /tabs >}}