diff --git a/docs/get_started/quickstart.mdx b/docs/get_started/quickstart.mdx index e4864f2e..a586b33b 100644 --- a/docs/get_started/quickstart.mdx +++ b/docs/get_started/quickstart.mdx @@ -13,526 +13,656 @@ import {Step} from "../../src/components/Stepper"; This guide takes you through your first steps with Restate. - + - -- TypeScript: Latest stable version of [NodeJS](https://nodejs.org/en/) >= v18.17.1 and [npm CLI](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) >= 9.6.7 -- Optional but recommended: [Install the Restate Server & CLI](/develop/local_dev#running-restate-server--cli-locally) - + + - TypeScript: Latest stable version of [NodeJS](https://nodejs.org/en/) >= v18.17.1 and [npm CLI](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) >= 9.6.7 + - Optional but recommended: [Install the Restate Server & CLI](/develop/local_dev#running-restate-server--cli-locally) + - + -Download the [Node template](https://github.com/restatedev/node-template-generator) with a skeleton of a Restate service. And install its dependencies: + Download the [Node template](https://github.com/restatedev/node-template-generator) with a skeleton of a Restate service. And install its dependencies: -```shell -npx -y @restatedev/create-app@latest && cd restate-node-template && \ -npm install -``` + ```shell + npx -y @restatedev/create-app@latest && cd restate-node-template && \ + npm install + ``` - - + + -Now, start developing your service in `src/app.ts`. Run it with [`ts-node-dev`](https://www.npmjs.com/package/ts-node-dev), and let it listen on port `9080` for requests: + Now, start developing your service in `src/app.ts`. Run it with [`ts-node-dev`](https://www.npmjs.com/package/ts-node-dev), and let it listen on port `9080` for requests: -```shell -npm run app-dev -``` + ```shell + npm run app-dev + ``` - + - -Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): + + Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): - + -```shell npx -npx @restatedev/restate-server -``` + ```shell npx + npx @restatedev/restate-server + ``` -``` shell Homebrew -brew install restatedev/tap/restate-server && restate-server -``` + ``` shell Homebrew + brew install restatedev/tap/restate-server && restate-server + ``` -```shell Docker -docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ - --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION -``` + ```shell Docker + docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ + --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION + ``` - + - + - + -Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: + Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: - + -```shell CLI -# link /develop/local_dev#running-restate-server--cli-locally -restate deployments register http://localhost:9080 -``` + ```shell CLI + # link /develop/local_dev#running-restate-server--cli-locally + restate deployments register http://localhost:9080 + ``` -```shell npx -npx @restatedev/restate deployments register http://localhost:9080 -``` + ```shell npx + npx @restatedev/restate deployments register http://localhost:9080 + ``` -```shell curl -curl localhost:9070/deployments -H 'content-type: application/json' \ - -d '{"uri": "http://localhost:9080"}' -``` + ```shell curl + curl localhost:9070/deployments -H 'content-type: application/json' \ + -d '{"uri": "http://localhost:9080"}' + ``` - + -If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. + If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. -
+
- Output + Output - ```shell - ❯ SERVICES THAT WILL BE ADDED: - - Greeter - Type: Service - HANDLER INPUT OUTPUT - greet value of content-type 'application/json' value of content-type 'application/json' + ```shell + ❯ SERVICES THAT WILL BE ADDED: + - Greeter + Type: Service + HANDLER INPUT OUTPUT + greet value of content-type 'application/json' value of content-type 'application/json' - ✔ Are you sure you want to apply those changes? · yes - ✅ DEPLOYMENT: - SERVICE REV - Greeter 1 - ``` + ✔ Are you sure you want to apply those changes? · yes + ✅ DEPLOYMENT: + SERVICE REV + Greeter 1 + ``` -
+
- + - + -```shell -curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi"' -``` + ```shell + curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi"' + ``` -You should now see printed as response: `Hi!` + You should now see printed as response: `Hi!` - - + + -
+
-Next: Build and run the app + Next: Build and run the app - Once you have implemented your service, build the app and run it with: + Once you have implemented your service, build the app and run it with: -```shell -npm run build -npm run app -``` + ```shell + npm run build + npm run app + ``` -
+
- - - - - Java: [JDK](https://whichjdk.com/) >= 11 - - Optional but recommended: [Install the Restate CLI](/develop/local_dev#running-restate-server--cli-locally) - - + + + + - Java: [JDK](https://whichjdk.com/) >= 11 + - Optional but recommended: [Install the Restate CLI](/develop/local_dev#running-restate-server--cli-locally) + + - -```shell CLI -# link(1:3) /develop/local_dev#running-restate-server--cli-locally -restate example java-hello-world-gradle && -cd java-hello-world-gradle -``` + + ```shell CLI + # link(1:3) /develop/local_dev#running-restate-server--cli-locally + restate example java-hello-world-gradle && + cd java-hello-world-gradle + ``` -```shell npx -npx @restatedev/restate example java-hello-world-gradle && -cd java-hello-world-gradle -``` + ```shell npx + npx @restatedev/restate example java-hello-world-gradle && + cd java-hello-world-gradle + ``` -```shell wget -wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-gradle.zip && - unzip java-hello-world-gradle.zip -d java-hello-world-gradle && - rm java-hello-world-gradle.zip && cd java-hello-world-gradle -``` + ```shell wget + wget https://github.com/restatedev/examples/releases/latest/download/java-hello-world-gradle.zip && + unzip java-hello-world-gradle.zip -d java-hello-world-gradle && + rm java-hello-world-gradle.zip && cd java-hello-world-gradle + ``` - + - - + + -You are all set to start developing your service. -Open the project in an IDE and configure it to build with Gradle. -Run your service and let it listen on port `9080` for requests: + You are all set to start developing your service. + Open the project in an IDE and configure it to build with Gradle. + Run your service and let it listen on port `9080` for requests: -```shell -./gradlew run -``` + ```shell + ./gradlew run + ``` - + - -Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): + + Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): - + - ```shell npx - npx @restatedev/restate-server - ``` + ```shell npx + npx @restatedev/restate-server + ``` - ``` shell Homebrew - brew install restatedev/tap/restate-server && restate-server - ``` + ``` shell Homebrew + brew install restatedev/tap/restate-server && restate-server + ``` - ```shell Docker - docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ - --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION - ``` + ```shell Docker + docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ + --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION + ``` - + - + - + -Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: + Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: - + - ```shell CLI - # link /develop/local_dev#running-restate-server--cli-locally - restate deployments register http://localhost:9080 - ``` + ```shell CLI + # link /develop/local_dev#running-restate-server--cli-locally + restate deployments register http://localhost:9080 + ``` - ```shell npx - npx @restatedev/restate deployments register http://localhost:9080 - ``` + ```shell npx + npx @restatedev/restate deployments register http://localhost:9080 + ``` - ```shell curl - curl localhost:9070/deployments -H 'content-type: application/json' \ - -d '{"uri": "http://localhost:9080"}' - ``` + ```shell curl + curl localhost:9070/deployments -H 'content-type: application/json' \ + -d '{"uri": "http://localhost:9080"}' + ``` - + -If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. + If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. -
+
- Output + Output - ```shell - ❯ SERVICES THAT WILL BE ADDED: - - Greeter - Type: Service - HANDLER INPUT OUTPUT - greet value of content-type 'application/json' value of content-type 'application/json' + ```shell + ❯ SERVICES THAT WILL BE ADDED: + - Greeter + Type: Service + HANDLER INPUT OUTPUT + greet value of content-type 'application/json' value of content-type 'application/json' - ✔ Are you sure you want to apply those changes? · yes - ✅ DEPLOYMENT: - SERVICE REV - Greeter 1 - ``` + ✔ Are you sure you want to apply those changes? · yes + ✅ DEPLOYMENT: + SERVICE REV + Greeter 1 + ``` -
+
- + - + -```shell -curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi!"' -``` + ```shell + curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi!"' + ``` -You should now see printed as response: `Hi!` + You should now see printed as response: `Hi!` - - + + -
- Next: Build the app +
+ Next: Build the app - Once you have implemented your service, build the app with: + Once you have implemented your service, build the app with: - ```shell - ./gradlew build - ``` + ```shell + ./gradlew build + ``` -
+
- - + + - - - Java/Kotlin: [JDK](https://whichjdk.com/) >= 11 - - Optional but recommended: [Install the Restate CLI](/develop/local_dev#running-restate-server--cli-locally) - + + - Java/Kotlin: [JDK](https://whichjdk.com/) >= 11 + - Optional but recommended: [Install the Restate CLI](/develop/local_dev#running-restate-server--cli-locally) + - + - + - ```shell CLI - # link(1:2) /develop/local_dev#running-restate-server--cli-locally - restate example kotlin-hello-world-gradle && - cd kotlin-hello-world-gradle - ``` + ```shell CLI + # link(1:2) /develop/local_dev#running-restate-server--cli-locally + restate example kotlin-hello-world-gradle && + cd kotlin-hello-world-gradle + ``` - ```shell npx - npx @restatedev/restate example kotlin-hello-world-gradle && - cd kotlin-hello-world-gradle - ``` + ```shell npx + npx @restatedev/restate example kotlin-hello-world-gradle && + cd kotlin-hello-world-gradle + ``` - ```shell wget - wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-gradle.zip && - unzip kotlin-hello-world-gradle.zip -d kotlin-hello-world-gradle && - rm kotlin-hello-world-gradle.zip && cd kotlin-hello-world-gradle - ``` + ```shell wget + wget https://github.com/restatedev/examples/releases/latest/download/kotlin-hello-world-gradle.zip && + unzip kotlin-hello-world-gradle.zip -d kotlin-hello-world-gradle && + rm kotlin-hello-world-gradle.zip && cd kotlin-hello-world-gradle + ``` - + - - + + - You are all set to start developing your service. - Open the project in an IDE and configure it to build with Gradle. - Run your service and let it listen on port `9080` for requests: + You are all set to start developing your service. + Open the project in an IDE and configure it to build with Gradle. + Run your service and let it listen on port `9080` for requests: - ```shell - ./gradlew run - ``` + ```shell + ./gradlew run + ``` - + - + - Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): + Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): - + - ```shell npx - npx @restatedev/restate-server - ``` + ```shell npx + npx @restatedev/restate-server + ``` - ``` shell Homebrew - brew install restatedev/tap/restate-server && restate-server - ``` + ``` shell Homebrew + brew install restatedev/tap/restate-server && restate-server + ``` - ```shell Docker - docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ - --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION - ``` + ```shell Docker + docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ + --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION + ``` - + - + - + - Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: + Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: - + - ```shell CLI - # link /develop/local_dev#running-restate-server--cli-locally - restate deployments register http://localhost:9080 - ``` + ```shell CLI + # link /develop/local_dev#running-restate-server--cli-locally + restate deployments register http://localhost:9080 + ``` - ```shell npx - npx @restatedev/restate deployments register http://localhost:9080 - ``` + ```shell npx + npx @restatedev/restate deployments register http://localhost:9080 + ``` - ```shell curl - curl localhost:9070/deployments -H 'content-type: application/json' \ - -d '{"uri": "http://localhost:9080"}' - ``` + ```shell curl + curl localhost:9070/deployments -H 'content-type: application/json' \ + -d '{"uri": "http://localhost:9080"}' + ``` - + - If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. + If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. -
+
- Output + Output - ```shell - ❯ SERVICES THAT WILL BE ADDED: - - Greeter - Type: Service - HANDLER INPUT OUTPUT - greet value of content-type 'application/json' value of content-type 'application/json' + ```shell + ❯ SERVICES THAT WILL BE ADDED: + - Greeter + Type: Service + HANDLER INPUT OUTPUT + greet value of content-type 'application/json' value of content-type 'application/json' - ✔ Are you sure you want to apply those changes? · yes - ✅ DEPLOYMENT: - SERVICE REV - Greeter 1 - ``` + ✔ Are you sure you want to apply those changes? · yes + ✅ DEPLOYMENT: + SERVICE REV + Greeter 1 + ``` -
+
- + - + - ```shell - curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi"' - ``` + ```shell + curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi"' + ``` - You should now see printed as response: `Hi!` + You should now see printed as response: `Hi!` - + - + -
+
- Next: Build the app + Next: Build the app - Once you have implemented your service, build the app with: + Once you have implemented your service, build the app with: - ```shell - ./gradlew build - ``` + ```shell + ./gradlew build + ``` -
+
- - + + - -- Go: >= 1.21.0 -- Optional but recommended: [Install the Restate Server & CLI](/develop/local_dev#running-restate-server--cli-locally) - + + - Go: >= 1.21.0 + - Optional but recommended: [Install the Restate Server & CLI](/develop/local_dev#running-restate-server--cli-locally) + - + - + - ```shell CLI - # link(1:2) /develop/local_dev#running-restate-server--cli-locally - restate example go-hello-world && - cd go-hello-world - ``` + ```shell CLI + # link(1:2) /develop/local_dev#running-restate-server--cli-locally + restate example go-hello-world && + cd go-hello-world + ``` - ```shell npx - npx @restatedev/restate example go-hello-world && - cd go-hello-world - ``` + ```shell npx + npx @restatedev/restate example go-hello-world && + cd go-hello-world + ``` - ```shell wget - wget https://github.com/restatedev/examples/releases/latest/download/go-hello-world.zip && - unzip go-hello-world.zip -d go-hello-world && - rm go-hello-world.zip && cd go-hello-world - ``` + ```shell wget + wget https://github.com/restatedev/examples/releases/latest/download/go-hello-world.zip && + unzip go-hello-world.zip -d go-hello-world && + rm go-hello-world.zip && cd go-hello-world + ``` - + - - + + -Now, start developing your service in `greeter.go`. Run it with `go run .`; it will listen on port 9080 for requests. + Now, start developing your service in `greeter.go`. Run it with `go run .`; it will listen on port 9080 for requests. - + - -Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): + + Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): - + -```shell npx -npx @restatedev/restate-server -``` + ```shell npx + npx @restatedev/restate-server + ``` -``` shell Homebrew -brew install restatedev/tap/restate-server && restate-server -``` + ``` shell Homebrew + brew install restatedev/tap/restate-server && restate-server + ``` -```shell Docker -docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ - --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION -``` + ```shell Docker + docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ + --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION + ``` - + - + - + -Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: + Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: - + -```shell CLI -# link /develop/local_dev#running-restate-server--cli-locally -restate deployments register http://localhost:9080 -``` + ```shell CLI + # link /develop/local_dev#running-restate-server--cli-locally + restate deployments register http://localhost:9080 + ``` -```shell npx -npx @restatedev/restate deployments register http://localhost:9080 -``` + ```shell npx + npx @restatedev/restate deployments register http://localhost:9080 + ``` -```shell curl -curl localhost:9070/deployments -H 'content-type: application/json' \ - -d '{"uri": "http://localhost:9080"}' -``` + ```shell curl + curl localhost:9070/deployments -H 'content-type: application/json' \ + -d '{"uri": "http://localhost:9080"}' + ``` - + -If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. + If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. -
+
- Output + Output - ```shell - ❯ SERVICES THAT WILL BE ADDED: - - Greeter - Type: Service - HANDLER INPUT OUTPUT - Greet value of content-type 'application/json' value of content-type 'application/json' + ```shell + ❯ SERVICES THAT WILL BE ADDED: + - Greeter + Type: Service + HANDLER INPUT OUTPUT + Greet value of content-type 'application/json' value of content-type 'application/json' - ✔ Are you sure you want to apply those changes? · yes - ✅ DEPLOYMENT: - SERVICE REV - Greeter 1 - ``` + ✔ Are you sure you want to apply those changes? · yes + ✅ DEPLOYMENT: + SERVICE REV + Greeter 1 + ``` -
+
- + - + -```shell -curl localhost:8080/Greeter/Greet -H 'content-type: application/json' -d '"Hi"' -``` + ```shell + curl localhost:8080/Greeter/Greet -H 'content-type: application/json' -d '"Hi"' + ``` -You should now see printed as response: `Hi!` + You should now see printed as response: `Hi!` - - + + -
+
-Next: Build and run the app + Next: Build and run the app - Once you have implemented your service, build the app with: + Once you have implemented your service, build the app with: -```shell -go build . -``` + ```shell + go build . + ``` -
+
- + + + + + - Python >= v3.11 + - Optional but recommended: [Install the Restate Server & CLI](/develop/local_dev#running-restate-server--cli-locally) + + + + + + ```shell CLI + # link(1:3) /develop/local_dev#running-restate-server--cli-locally + restate example python-hello-world && + cd python-hello-world + ``` + + ```shell npx + npx @restatedev/restate example python-hello-world && + cd python-hello-world + ``` + + ```shell wget + wget https://github.com/restatedev/examples/releases/latest/download/python-hello-world.zip && + unzip python-hello-world.zip -d python-hello-world && + rm python-hello-world.zip && cd python-hello-world + ``` + + + + + + + Create a `venv` and install the requirements: + + ```shell + python3 -m venv .venv + source .venv/bin/activate + pip install -r requirements.txt + ``` + + Now, start developing your service in `example.py`. Run it with a [Hypercorn](https://pypi.org/project/Hypercorn/) server, and let it listen on port `9080` for requests: + + ```shell + python -m hypercorn --config hypercorn-config.toml example:app + ``` + + + + + Restate is a single self-contained binary. No external dependencies needed. Run it locally via ([or download the binaries](/develop/local_dev#running-restate-server--cli-locally)): + + + + + ```shell npx + npx @restatedev/restate-server + ``` + + ``` shell Homebrew + brew install restatedev/tap/restate-server && restate-server + ``` + + ```shell Docker + docker run --name restate_dev --rm -p 8080:8080 -p 9070:9070 -p 9071:9071 \ + --add-host=host.docker.internal:host-gateway docker.io/restatedev/restate:VAR::RESTATE_VERSION + ``` + + + + + + + + Tell Restate where the service is running, so Restate can discover and register the services and handlers behind this endpoint: + + + + ```shell CLI + # link /develop/local_dev#running-restate-server--cli-locally + restate deployments register http://localhost:9080 + ``` + + ```shell npx + npx @restatedev/restate deployments register http://localhost:9080 + ``` + + ```shell curl + curl localhost:9070/deployments -H 'content-type: application/json' \ + -d '{"uri": "http://localhost:9080"}' + ``` + + + + If you run Restate with Docker, use `http://host.docker.internal:9080` instead of `http://localhost:9080`. + +
+ + Output + + ```shell + ❯ SERVICES THAT WILL BE ADDED: + - Greeter + Type: Service + HANDLER INPUT OUTPUT + greet value of content-type 'application/json' value of content-type 'application/json' + + + ✔ Are you sure you want to apply those changes? · yes + ✅ DEPLOYMENT: + SERVICE REV + Greeter 1 + ``` + +
+ + + + + + ```shell + curl localhost:8080/Greeter/greet -H 'content-type: application/json' -d '"Hi"' + ``` + + You should now see printed as response: `Hi!` + + + + + +