dapr / docs

Dapr user documentation, used to build docs.dapr.io

Dapr documentation

If you are looking to explore the Dapr documentation, please go to the documentation website:

https://docs.dapr.io

This repo contains the markdown files which generate the above website. See below for guidance on running with a local environment to contribute to the docs.

Branch guidance

The Dapr docs handles branching differently than most code repositories. Instead of having a master or main branch, every branch is labeled to match the major and minor version of a runtime release.

The following branches are currently maintained:

Branch	Website	Description
v1.14 (primary)	https://docs.dapr.io	Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here.
v1.15 (pre-release)	https://v1-15.docs.dapr.io/	Pre-release documentation. Doc updates that are only applicable to v1.15+ go here.

For more information visit the Dapr branch structure document.

Contribution guidelines

Before making your first contribution, make sure to review the contributing section in the docs.

Overview

The Dapr docs are built using Hugo with the Docsy theme, hosted on an Azure Static Web App.

The daprdocs directory contains the hugo project, markdown files, and theme configurations.

Setup with a devcontainer

This repository comes with a devcontainer configuration that automatically installs all the required dependencies and VSCode extensions to build and run the docs.

This devcontainer can be used to develop locally with VSCode or via GitHub Codespaces completely in the browser. Other IDEs that support devcontainers can be used but won't have the extensions preconfigured and will likely have different performance characteristics.

Pre-requisites

• Docker Desktop
• VSCode

Environment setup

1. Fork and clone this repository.

2. Open the forked repository in VS Code

code .

1. When prompted, click "Reopen in Container" to open the repository in the devcontainer.

Continue with the Run local server steps.

Setup without a devcontainer

Pre-requisites

• Hugo extended version
• Node.js

Environment setup

1. Ensure pre-requisites are installed.

2. Fork and clone this repository.

3. Change to daprdocs directory:

cd ./daprdocs

4. Update submodules:

git submodule update --init --recursive

5. Install npm packages:

npm install

Run local server

1. Make sure you're in the daprdocs directory
2. Run

hugo server

3. Navigate to http://localhost:1313/

Update docs

1. Ensure you are in your forked repo
2. Create new branch
3. Commit and push changes to forked branch
4. Submit pull request from downstream branch to the upstream branch for the correct version you are targeting
5. Staging site will automatically get created and linked to PR to review and test

Code of Conduct

Please refer to our Dapr community code of conduct.

docs's Issues

Hello World sample on local Mac trouble: Temporary error when accepting new connections

Following the instructions.

stephenrwalli$ dapr list
No dapr instances found.
stephenrwalli$ dapr --version
cli version: 0.4.0-alpha.2
runtime version: edge
stephenrwalli$ dapr init
⌛  Making the jump to hyperspace...
✅  Downloading binaries and setting up components...
✅  Success! Dapr is up and running
stephenrwalli$ dapr run --app-id mynode --app-port 3000 --port 3500 node app.js
ℹ️  Starting Dapr with id mynode. HTTP Port: 3500. gRPC Port: 61542
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="starting Dapr Runtime -- version edge -- commit f62dc31-dirty"
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="log level set to: info"
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="standalone mode configured"
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="dapr id: mynode"
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="loaded component messagebus (pubsub.redis)"
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="loaded component statestore (state.redis)"
== DAPR == time="2019-10-10T20:52:38-07:00" level=info msg="application protocol: http. waiting on port 3000"
✅  You're up and running! Both Dapr and your app logs will appear here.

== APP == Node App listening on port 3000!
== DAPR == time="2019-10-10T20:52:39-07:00" level=info msg="application discovered on port 3000"
== DAPR == 2019/10/10 20:52:39 redis: connecting to localhost:6379
== DAPR == 2019/10/10 20:52:39 redis: connected to localhost:6379 (localAddr: [::1]:61570, remAddr: [::1]:6379)
== DAPR == time="2019-10-10T20:52:39-07:00" level=info msg="actor runtime started. actor idle timeout: 1h0m0s. actor scan interval: 30s"
== DAPR == time="2019-10-10T20:52:39-07:00" level=info msg="actors: starting connection attempt to placement service at localhost:50005"
== DAPR == time="2019-10-10T20:52:39-07:00" level=info msg="http server is running on port 3500"
== DAPR == time="2019-10-10T20:52:39-07:00" level=info msg="gRPC server is running on port 61542"
== DAPR == time="2019-10-10T20:52:39-07:00" level=info msg="actors: established connection to placement service at localhost:50005"
== DAPR == 2019/10/10 20:53:13 Temporary error when accepting new connections: accept tcp4 0.0.0.0:3500: accept: too many open files
== DAPR == time="2019-10-10T20:53:14-07:00" level=warning msg="failed to broadcast address to local network: could not determine host IP addresses for Stephens-MacBook-Pro."
== DAPR == time="2019-10-10T20:53:14-07:00" level=info msg="dapr initialized. Status: Running. Init Elapsed 35616.638603ms"

Note the logged error above. Also confused at the dapr runtime version 'edge'. I did update my version of dapr because I was running an older version from the other day that failed. I stopped dapr, stopped and removed running containers, downloaded and installed the new CLI, and ran dapr init again.

In another terminal window.

stephenrwalli$ docker ps -a
CONTAINER ID        IMAGE                                COMMAND                  CREATED              STATUS              PORTS                      NAMES
57b860983ac3        actionscore.azurecr.io/dapr:latest   "./placement"            About a minute ago   Up About a minute   0.0.0.0:50005->50005/tcp   dapr_placement
b8f1fb5626d8        redis                                "docker-entrypoint.s…"   About a minute ago   Up About a minute   0.0.0.0:6379->6379/tcp     elated_engelbart
stephenrwalli$ curl -XPOST -d @sample.json http://localhost:3500/v1.0/invoke/mynode/method/neworder
curl: (52) Empty reply from server
stephenrwalli$ node --version
v12.11.1
stephenrwalli$ dapr --version
cli version: 0.4.0-alpha.2
runtime version: edge
stephenrwalli$ docker --version
Docker version 19.03.2, build 6a30dfc
stephenrwalli$

Running on MacOS 10.14.6.
Ideas?

How does Dapr integrate with KEDA

KEDA integrates with Dapr, and we should show an Dapr + KEDA sample to show autoscaling in Kubernetes.

Clearly communicate Azure Managed Redis only supports state not pub/sub in the Redis doc

Create new single page Getting-Started/README.md with structured walkthrough linked from dapr/dapr/README.md

404 for link on actor_pattern.md

https://github.com/dapr/docs/blob/master/concepts/actor/actor_pattern.md

following link Enabling the Actor Pattern results in 404

link points to https://github.com/dapr/docs/blob/master/topics/enable_actor_pattern.md

Update and add new actor conceptual docs

https://github.com/dapr/docs/tree/master/concepts/actor

Don't use 'X-' in HTTP headers

The IETF guidance to prefix X- to experimental headers or to other extension field types has been deprecated since June 2012, per RFC 6648.

I'd suggest prefixing with Dapr- where you feel namespacing is necessary.

Docs should contain API endpoints for interacting with dapr and how dapr interacts with user code

For example dapr service invocation is triggered by:
http://localhost:<DAPR_HTTP_PORT>/v1.0/invoke/<id>/method/<method-name>

and reaches out to the app by:

http://localhost:<app-port>/<method-name>

Rename Actions to Dapr in Docs

Typos in API reference State Management

Expected Behavior

Should have no typos.

Actual Behavior

Found some typos in the state.md file.
Please see the PR #176 for details.

Steps to Reproduce the Problem

Installing dapr in standalone mode on Windows need to switch to Linux containers in Docker Desktop

Expected Behavior

Following the instructions in https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md for Windows, after running "dapr init", I expect to see daprio/dapr:latest and redis container images running.

Actual Behavior

I did not see daprio/dapr:latest and redis containers. Below is what I saw.

PS C:\dapr> dapr init
Making the jump to hyperspace... Downloading binaries and setting up components... Success! Dapr is up and running
PS C:\dapr> docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

After I switch Docker Desktop to use Linux containers, I was able to see the two containers running after 'dapr init'.

Steps to Reproduce the Problem

Set Docker Desktop to use Windows container and then run 'dapr init'.

Write security conceptual doc

https://github.com/dapr/docs/blob/master/concepts/security/security.md

Write terminology conceptual doc

https://github.com/dapr/docs/blob/master/concepts/terminology/terminology.md

Broken links in concepts/actor/enable_actor_pattern.md

There is a link to ../concepts/actor/actor_pattern.md should be actor_pattern.md

Ther is another link to: [reliable messaging](TBD) which needs to be defined.

Ensure strong clear guidance on how to version your app when using Dapr

• Create How-To on how to both version your app (multiple versions of the new order method)
• At least one sample showing versioning
• Guidance on how the developer knows what version of Dapr runtime is running at any one time so the App can be Dapr API/functionality aware.

what is the use of dapr placement running in docker while standalone mode?

hi,
try with standalone sample, and notice there is a dapr_placement running in the docker, i try to find something about it in doc but no luck, would anyone tell me what it is?
is it the dapr runtime in below overview picture?

Write service invocation conceptual doc

https://github.com/dapr/docs/blob/master/concepts/service-invocation/service-invocation.md

Update architectural diagrams

Update:

• https://github.com/dapr/dapr/raw/master/img/dapr_standalone.jpg
• https://github.com/dapr/dapr/raw/master/img/dapr_k8s.jpg
• Inside Dapr runtime

Update Contribution guidance to include CLA information

Update Contribution guidance to include CLA information

Write How To for stateful service with concurrency guarantees

Remove the /docs folder from actionscore

All docs are now updated in the docs repo and now in separate repos.
Fix up doc links in actionscore readme.md

Convert Spec to "API Reference" docs in the Docs repo and remove the Spec repo

Improve Actors conceptual docs and add dotnet sdk usage.

Where should getting-started/readme.md link to 'dapr cli' point for installation?

It presently points to https://github.com/dapr/cli/releases.
This means a new user needs to choose a release without context.

Pointing to https://github.com/dapr/cli gives them useful info (but the same general releases link). Is there a way to force a general 'stable' releases link equivalent where the downloads actually exist (i.e. https://github.com/dapr/cli/releases/tag/v0.3.0-alpha.1)?

Broken image links in docs

The following docs have broken image links:

• https://github.com/dapr/docs/blob/master/best-practices/troubleshooting/profiling_debugging.md
• https://github.com/dapr/docs/blob/master/best-practices/troubleshooting/tracing.md
• https://github.com/dapr/docs/blob/master/concepts/actor/actors_integration.md
• https://github.com/dapr/docs/blob/master/concepts/actor/enable_actor_pattern.md

The links just need to be adusted from ../imgs to ../../images

Top-level conceptual doc in README is updated

Include short concise summary of each in top level doc.

Identical Redis configuration for persistence and pub/sub

The document describing how to set up Redis contains identical configuration for persistence and pub/sub.

By looking at a pub/sub sample configuration, it appears they have at least different spec.type properties.

Is that currently the only difference? If so, I can contribute a quick fix for this.

Write Tracing conceptual doc

https://github.com/dapr/docs/blob/master/concepts/tracing-logging/tracing-logging.md

Broken link to distributed_tracing.md (from best-practices/troubleshooting/tracing.md)

Inside of best-practices/troubleshooting/tracing.md there is a link to https://github.com/dapr/docs/blob/master/best-practices/distributed_tracing.md

I don't see this doc (distributed_tracing.md) anywhere in this repository.

404 for links in best-practices/troubleshooting/common_issues.md

There are two broken links that are referencing ../components/redis.md when they should be referencing ../../concepts/components/redis.md

There is also one link referencing https://github.com/actionscore/spec

How does Dapr work with service meshes and guidance

Diagrams to show Dapr using a service mesh such as Istio or LinkerD and guidance on when to use which, especially with method invocation.

Setup CI build and PR gate

Terminology link 404s from the Concepts/README.md and it should be first

Terminology doc

Create "Core concepts" diagram for Getting Started

Improve State Management concepts in topics section in new docs repo

Will start with state management

Write How To for stateful service with consistency guarantees

"Building Block" concept documentation

Including requirements for new "building block" proposal/implementation.

Remove tutorials documentation until improved

Replace with getting started with Actors link on main page.

Documentation dapr-operator Readme link does not available in installing-dapr-on-a-kubernetes-cluster

this link does not exist http://github.com/dapr/dapr/blob/master/charts/dapr-operator/README.md
on https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md#installing-dapr-on-a-kubernetes-cluster

Create How-Tos with structure of clear "problem & solution"

E.g. How to use consistency with "old world" and "new world"

Docs with code snippets.

Broken links in howto/setup-secret-store/azure-keyvault.md

The links to the samples are pointing to

• https://github.com/actionscore/actions/tree/master/samples/1.hello-world
• https://github.com/actionscore/actions/tree/master/samples/2.hello-kubernetes

Write Pub/sub conceptual doc

https://github.com/dapr/docs/blob/master/concepts/publish-subscribe-messaging/pub-sub-messaging.md

Update docs with gRPC uses

Once dapr/dapr#526 is merged, we need to revisit docs and insert gRPC examples where appropriate.

Describe how to visualize and query the stored state including actor state

These articles describes how to view/query the state data for both Redis and CosmosDB whether the state is stored via the /state call or via actors. Many people have asked what the schema is like and how to do the query.

Typos in docs

Expected Behavior

Should not have typos.

Actual Behavior

I found many typos in the documents.

Steps to Reproduce the Problem

Service invocation documentation should document receiving endpoint

Flat list of API at 101 level

Need to surface note regarding auto-generating port in the CLI documentation

Currently, the following note regarding the port parameter is in the doc for Hello World; it should also be made available in the CLI documentation.

---

Note: The Actions --port parameter with the run command is optional, and if not supplied, a random available port is used.

---

Improve and document external IP for MiniKube setup