From fde7bf92aa7ed00f4754d832653b5266dd909ca2 Mon Sep 17 00:00:00 2001 From: Joshua Mo Date: Mon, 21 Oct 2024 18:34:42 +0100 Subject: [PATCH 1/6] docs: give every template a README.md --- actix-web/hello-world/README.md | 5 +++++ axum/hello-world/README.md | 5 +++++ axum/metadata/README.md | 5 +++++ axum/turso/README.md | 11 +++++++++++ axum/websocket/README.md | 5 +++++ custom-resource/pdo/README.md | 5 +++++ custom-service/none/README.md | 7 +++++++ other/feature-flags/README.md | 5 +++++ poem/hello-world/README.md | 5 +++++ rocket/hello-world/README.md | 5 +++++ rocket/postgres/README.md | 13 +++++++++++++ rocket/static-files/README.md | 3 +++ rocket/workspace/README.md | 5 +++++ salvo/hello-world/README.md | 5 +++++ shuttle-cron/README.md | 16 ++++++++++++++++ templates.toml | 2 +- thruster/hello-world/README.md | 5 +++++ tide/hello-world/README.md | 5 +++++ tower/hello-world/README.md | 5 +++++ tracing/custom-tracing-subscriber/README.md | 10 ++++++++++ warp/hello-world/README.md | 5 +++++ 21 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 actix-web/hello-world/README.md create mode 100644 axum/hello-world/README.md create mode 100644 axum/metadata/README.md create mode 100644 axum/turso/README.md create mode 100644 axum/websocket/README.md create mode 100644 custom-resource/pdo/README.md create mode 100644 custom-service/none/README.md create mode 100644 other/feature-flags/README.md create mode 100644 poem/hello-world/README.md create mode 100644 rocket/hello-world/README.md create mode 100644 rocket/postgres/README.md create mode 100644 rocket/static-files/README.md create mode 100644 rocket/workspace/README.md create mode 100644 salvo/hello-world/README.md create mode 100644 shuttle-cron/README.md create mode 100644 thruster/hello-world/README.md create mode 100644 tide/hello-world/README.md create mode 100644 tower/hello-world/README.md create mode 100644 tracing/custom-tracing-subscriber/README.md create mode 100644 warp/hello-world/README.md diff --git a/actix-web/hello-world/README.md b/actix-web/hello-world/README.md new file mode 100644 index 00000000..ce525aa3 --- /dev/null +++ b/actix-web/hello-world/README.md @@ -0,0 +1,5 @@ +A `Hello world!` example for using Actix Web with Shuttle. + +## Example usage + +Run the app and go to . diff --git a/axum/hello-world/README.md b/axum/hello-world/README.md new file mode 100644 index 00000000..9fac6409 --- /dev/null +++ b/axum/hello-world/README.md @@ -0,0 +1,5 @@ +A `Hello world!` example for using Axum with Shuttle. + +## Example usage + +Run the app and go to . diff --git a/axum/metadata/README.md b/axum/metadata/README.md new file mode 100644 index 00000000..3ec6ab70 --- /dev/null +++ b/axum/metadata/README.md @@ -0,0 +1,5 @@ +An example that showcases Shuttle metadata at the base route using Axum. + +## Example usage + +Run the app and go to . diff --git a/axum/turso/README.md b/axum/turso/README.md new file mode 100644 index 00000000..2a9abddd --- /dev/null +++ b/axum/turso/README.md @@ -0,0 +1,11 @@ +An example that showcases using Turso with Axum and Shuttle. + +## Example usage + +Set your `TURSO_DB_TOKEN` in Secrets.toml and Turso database in `src/main.rs` in the annotation. + +Run the app, then try it out with the following `curl` command: + +```sh +curl http://localhost:8000 -H 'content-type: application/json' --data '{"uid":"1","email":"foo@bar.xyz"}' +``` diff --git a/axum/websocket/README.md b/axum/websocket/README.md new file mode 100644 index 00000000..4465be68 --- /dev/null +++ b/axum/websocket/README.md @@ -0,0 +1,5 @@ +This template shows how to use websockets with Axum in a Shuttle project. + +## Example usage + +Run the project and visit to try it out. diff --git a/custom-resource/pdo/README.md b/custom-resource/pdo/README.md new file mode 100644 index 00000000..8a9b8161 --- /dev/null +++ b/custom-resource/pdo/README.md @@ -0,0 +1,5 @@ +This template shows how to create your own custom Shuttle resource in a Shuttle project, using Axum for the `main.rs` file to set up the router. + +## Example usage + +Run the project and visit . diff --git a/custom-service/none/README.md b/custom-service/none/README.md new file mode 100644 index 00000000..dd79e3ce --- /dev/null +++ b/custom-service/none/README.md @@ -0,0 +1,7 @@ +This template shows how to create your own custom Shuttle service that can run anything HTTP-based. + +## Example usage + +Set up whatever you want to do in the `bind()` function, then visit (or your relevant routes) to try it out. + +Variables from resource annotations can be added to `MyService` struct to use them in the `bind()` function. diff --git a/other/feature-flags/README.md b/other/feature-flags/README.md new file mode 100644 index 00000000..992429ac --- /dev/null +++ b/other/feature-flags/README.md @@ -0,0 +1,5 @@ +An example that showcases how to use feature flags with Shuttle (see `Cargo.toml`). + +## Example usage + +Run the project and visit . diff --git a/poem/hello-world/README.md b/poem/hello-world/README.md new file mode 100644 index 00000000..7305bd21 --- /dev/null +++ b/poem/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `poem` web service framework with Shuttle. + +## Example usage + +Run the project and visit . diff --git a/rocket/hello-world/README.md b/rocket/hello-world/README.md new file mode 100644 index 00000000..2f2f92a9 --- /dev/null +++ b/rocket/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `rocket` web service framework with Shuttle. + +## Example usage + +Run the project and visit . diff --git a/rocket/postgres/README.md b/rocket/postgres/README.md new file mode 100644 index 00000000..03b20c60 --- /dev/null +++ b/rocket/postgres/README.md @@ -0,0 +1,13 @@ +# Shuttle shared Postgres DB with Rocket + +This template shows how to connect a Postgres database and use it for a simple TODO list app. + +## Example usage + +```bash +curl -X POST -H 'content-type: application/json' localhost:8000/todo --data '{"note":"My todo"}' +# {"id":1,"note":"My todo"} + +curl localhost:8000/todos/1 +# {"id":1,"note":"My todo"} +``` diff --git a/rocket/static-files/README.md b/rocket/static-files/README.md new file mode 100644 index 00000000..c4d22a1c --- /dev/null +++ b/rocket/static-files/README.md @@ -0,0 +1,3 @@ +# Serving Static Assets with Rocket + +This example shows how to serve static assets using [axum](https://github.com/rwf2/rocket) and Shuttle. diff --git a/rocket/workspace/README.md b/rocket/workspace/README.md new file mode 100644 index 00000000..aeb20d6c --- /dev/null +++ b/rocket/workspace/README.md @@ -0,0 +1,5 @@ +This example shows how to use a Cargo workspace with Shuttle using the `rocket` web service frameowrk. + +## Example usage + +Run the project and visit . diff --git a/salvo/hello-world/README.md b/salvo/hello-world/README.md new file mode 100644 index 00000000..64afac27 --- /dev/null +++ b/salvo/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `salvo` web service framework with Shuttle. + +## Example usage + +Run the project and visit . diff --git a/shuttle-cron/README.md b/shuttle-cron/README.md new file mode 100644 index 00000000..2677ff2f --- /dev/null +++ b/shuttle-cron/README.md @@ -0,0 +1,16 @@ +# `shuttle-cron` + +A service that prints out a log message at specified cron-style intervals. + +This example uses the `apalis` framework to be able to carry out cronjobs. A struct is defined that has some given data in it, and is stored in the Apalis monitor. We also implement a struct that holds a `chrono::DateTime`, which `apalis` uses internally for cron job streaming. + +When the cron job is called, the data is grabbed from the `JobContext` and we then execute the job. + +The actual function to be ran itself is stored in `job_fn()` in the main function, as a function pointer. + +# Usage +Run `shuttle run` to spin up the service locally. + +You can change the behavior of the cronjob by editing the `execute()` function for `CronjobData`. + +Note that the run method doesn't have to be an implementation method for `CronjobData` - you can write your own! diff --git a/templates.toml b/templates.toml index 1e9af22e..000e5862 100644 --- a/templates.toml +++ b/templates.toml @@ -49,7 +49,7 @@ template = "axum" [starters.bevy-hello-world] title = "Bevy" description = "Data driven game engine that compiles to WASM" -path = "bevy/hello-world" +path = "bevy/hello-world/" use_cases = ["Web app", "Game"] tags = ["bevy", "axum"] diff --git a/thruster/hello-world/README.md b/thruster/hello-world/README.md new file mode 100644 index 00000000..40cc4396 --- /dev/null +++ b/thruster/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `thruster` web service framework with Shuttle. + +## Example usage + +Run the project and visit . diff --git a/tide/hello-world/README.md b/tide/hello-world/README.md new file mode 100644 index 00000000..4e35b652 --- /dev/null +++ b/tide/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `tide` web service framework with Shuttle. + +## Example usage + +Run the project and visit . diff --git a/tower/hello-world/README.md b/tower/hello-world/README.md new file mode 100644 index 00000000..f350a502 --- /dev/null +++ b/tower/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `tower` web service framework (with `hyper`) with Shuttle. + +## Example usage + +Run the project and visit . diff --git a/tracing/custom-tracing-subscriber/README.md b/tracing/custom-tracing-subscriber/README.md new file mode 100644 index 00000000..0c683a97 --- /dev/null +++ b/tracing/custom-tracing-subscriber/README.md @@ -0,0 +1,10 @@ +An example that showcases using a custom `tracing-subscriber` with Shuttle. + +Notes: +- `default-features` is disabled on `shuttle-runtime` crate to allow this to be possible + +## Example usage + +Run the project and visit . + +You can also additionally adjust the custom tracing subscriber as you want. diff --git a/warp/hello-world/README.md b/warp/hello-world/README.md new file mode 100644 index 00000000..3051701d --- /dev/null +++ b/warp/hello-world/README.md @@ -0,0 +1,5 @@ +An example that showcases using the `warp` web service framework (with `hyper`) with Shuttle. + +## Example usage + +Run the project and visit . From 97348ccc5717ed6539d65354aba0ae8ef75c61c2 Mon Sep 17 00:00:00 2001 From: Joshua Mo Date: Tue, 22 Oct 2024 01:30:32 +0100 Subject: [PATCH 2/6] feat: fix templates.toml --- templates.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates.toml b/templates.toml index 000e5862..1e9af22e 100644 --- a/templates.toml +++ b/templates.toml @@ -49,7 +49,7 @@ template = "axum" [starters.bevy-hello-world] title = "Bevy" description = "Data driven game engine that compiles to WASM" -path = "bevy/hello-world/" +path = "bevy/hello-world" use_cases = ["Web app", "Game"] tags = ["bevy", "axum"] From cf09fdf23ce4dc08a61482609f9e2b66a3bbc640 Mon Sep 17 00:00:00 2001 From: Joshua Mo Date: Wed, 23 Oct 2024 11:19:49 +0100 Subject: [PATCH 3/6] fix: typo --- rocket/static-files/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rocket/static-files/README.md b/rocket/static-files/README.md index c4d22a1c..0e633aec 100644 --- a/rocket/static-files/README.md +++ b/rocket/static-files/README.md @@ -1,3 +1,3 @@ # Serving Static Assets with Rocket -This example shows how to serve static assets using [axum](https://github.com/rwf2/rocket) and Shuttle. +This example shows how to serve static assets using [rocket](https://github.com/rwf2/rocket) and Shuttle. From b6cc2677f2d5ab1e4eeaae962fa0f294b4dbe93c Mon Sep 17 00:00:00 2001 From: Joshua Mo Date: Wed, 23 Oct 2024 12:12:58 +0100 Subject: [PATCH 4/6] docs: standardise readmes --- actix-web/README.md | 2 +- actix-web/clerk/README.md | 2 +- actix-web/cookie-authentication/README.md | 4 +++- actix-web/hello-world/README.md | 4 +++- actix-web/postgres/README.md | 6 ++++-- actix-web/static-files/README.md | 2 +- actix-web/websocket-actorless/README.md | 4 ++-- axum/hello-world/README.md | 4 +++- axum/htmx-crud/README.md | 4 ++-- axum/jwt-authentication/README.md | 6 +++++- axum/metadata/README.md | 4 +++- axum/oauth2/README.md | 4 ++-- axum/openai/README.md | 4 ++++ axum/postgres/README.md | 6 ++++-- axum/qdrant/README.md | 4 ++-- axum/static-files/README.md | 6 +++++- axum/turso/README.md | 4 +++- axum/websocket/README.md | 4 +++- bevy/hello-world/README.md | 4 +++- custom-resource/pdo/README.md | 4 +++- custom-service/none/README.md | 4 +++- fullstack-templates/saas/README.md | 2 +- loco/hello-world/README.md | 8 ++------ other/feature-flags/README.md | 4 +++- other/standalone-binary/README.md | 6 ++++++ poem/hello-world/README.md | 6 ++++-- poise/hello-world/README.md | 2 ++ rocket/dyn-templates/README.md | 6 +++++- rocket/hello-world/README.md | 4 +++- rocket/jwt-authentication/README.md | 4 ++-- rocket/opendal-memory/README.md | 9 +++++++++ rocket/postgres/README.md | 6 ++++-- rocket/secrets/README.md | 9 ++++++++- rocket/static-files/README.md | 6 +++++- rocket/url-shortener/README.md | 4 ++-- rocket/workspace/README.md | 3 ++- salvo/hello-world/README.md | 4 +++- salvo/image-rescaler/README.md | 4 +++- serenity/hello-world/README.md | 2 ++ serenity/postgres/README.md | 2 ++ serenity/weather-forecast/README.md | 4 ++++ shuttle-cron/README.md | 3 ++- thruster/hello-world/README.md | 4 +++- tide/hello-world/README.md | 4 +++- tower/hello-world/README.md | 2 ++ tracing/custom-tracing-subscriber/README.md | 4 +++- warp/hello-world/README.md | 4 +++- 47 files changed, 148 insertions(+), 54 deletions(-) diff --git a/actix-web/README.md b/actix-web/README.md index 0c2802ba..9750dc7f 100644 --- a/actix-web/README.md +++ b/actix-web/README.md @@ -1,4 +1,4 @@ -# Actix Web with shuttle +# Actix Web with Shuttle Normally one would configure an application with [Actix Web](https://docs.rs/actix-web/latest/actix_web/index.html) using the [App](https://docs.rs/actix-web/latest/actix_web/struct.App.html) struct. However, shuttle needs to move the users configuration across threads to start the server on our backend, and the `App` struct is `!Send` and `!Sync`. diff --git a/actix-web/clerk/README.md b/actix-web/clerk/README.md index 621fd7cd..e66de052 100644 --- a/actix-web/clerk/README.md +++ b/actix-web/clerk/README.md @@ -1,4 +1,4 @@ -# Using Clerk auth with a Rust Actix web backend +# Actix Web with Clerk auth This template uses Actix-web and the clerk-rs crate for providing authentication from Clerk in the backend. diff --git a/actix-web/cookie-authentication/README.md b/actix-web/cookie-authentication/README.md index a54d8987..9e7e5773 100644 --- a/actix-web/cookie-authentication/README.md +++ b/actix-web/cookie-authentication/README.md @@ -1,7 +1,9 @@ -# Cookie authentication with actix-session +# Actix Web Cookie authentication with actix-session This template uses the [actix_identity](https://docs.rs/actix-identity) and [actix_session](https://docs.rs/actix-session) crates to manage user sessions. +## How to use + Running the project and visiting will show the currently logged in user. Visiting will log you in as `user1` (no authentication logic is in place). Visiting will log you out again. diff --git a/actix-web/hello-world/README.md b/actix-web/hello-world/README.md index ce525aa3..2d61d499 100644 --- a/actix-web/hello-world/README.md +++ b/actix-web/hello-world/README.md @@ -1,5 +1,7 @@ +# Actix Web Hello World + A `Hello world!` example for using Actix Web with Shuttle. -## Example usage +## How to use this template Run the app and go to . diff --git a/actix-web/postgres/README.md b/actix-web/postgres/README.md index 65fa4d2d..972195f8 100644 --- a/actix-web/postgres/README.md +++ b/actix-web/postgres/README.md @@ -1,8 +1,10 @@ -# Shuttle shared Postgres DB with Actix Web +# Actix Web with Shuttle Shared DB (Postgres) This template shows how to connect a Postgres database and use it for a simple TODO list app. -## Example usage +## How to use this template: + +Run the project then run the following `curl` commands below: ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todos --data '{"note":"My todo"}' diff --git a/actix-web/static-files/README.md b/actix-web/static-files/README.md index 5f770281..1190ccef 100644 --- a/actix-web/static-files/README.md +++ b/actix-web/static-files/README.md @@ -1,4 +1,4 @@ -# Actix Web static files +## Actix Web Static Files This template uses `actix_files` to serve the files in the `assets` directory. diff --git a/actix-web/websocket-actorless/README.md b/actix-web/websocket-actorless/README.md index 19340c2c..b6df6f32 100644 --- a/actix-web/websocket-actorless/README.md +++ b/actix-web/websocket-actorless/README.md @@ -1,7 +1,7 @@ -# Actix Web actorless websockets +# Actix Web Actorless Websockets This template shows how to use actorless websockets to build an API monitoring service and a simple chat app. -## Example usage +## How to use this template Run the app and go to . diff --git a/axum/hello-world/README.md b/axum/hello-world/README.md index 9fac6409..f06be717 100644 --- a/axum/hello-world/README.md +++ b/axum/hello-world/README.md @@ -1,5 +1,7 @@ +# Axum Hello World + A `Hello world!` example for using Axum with Shuttle. -## Example usage +## How to use this template Run the app and go to . diff --git a/axum/htmx-crud/README.md b/axum/htmx-crud/README.md index 9d09c004..b8842d18 100644 --- a/axum/htmx-crud/README.md +++ b/axum/htmx-crud/README.md @@ -1,9 +1,9 @@ -# Axum + htmx +# Axum with HTMx This is an example of how you can use Shuttle with Axum, Askama and htmx to create a frontend that's easily extendable and requires zero framework knowledge, while being able to easily inject variables from the backend into the frontend. The app is a TODO list with a main page and an event stream page. -## Usage +## How to use this template Run the app and go to to add and remove TODOs from the list. diff --git a/axum/jwt-authentication/README.md b/axum/jwt-authentication/README.md index 15ecfdac..c43d7aba 100644 --- a/axum/jwt-authentication/README.md +++ b/axum/jwt-authentication/README.md @@ -1,3 +1,7 @@ -# JWT authentication in Axum +# Axum JWT authentication This template uses the `jsonwebtoken` crate to encode and decode claims in a JWT, which clients use in the Authorization HTTP header to access protected resources (endpoints). + +## Example usage + +Run the app and go to . diff --git a/axum/metadata/README.md b/axum/metadata/README.md index 3ec6ab70..24206b5a 100644 --- a/axum/metadata/README.md +++ b/axum/metadata/README.md @@ -1,5 +1,7 @@ +# Axum with Shuttle metadata + An example that showcases Shuttle metadata at the base route using Axum. -## Example usage +## How to use this template Run the app and go to . diff --git a/axum/oauth2/README.md b/axum/oauth2/README.md index a867d286..f044b768 100644 --- a/axum/oauth2/README.md +++ b/axum/oauth2/README.md @@ -1,8 +1,8 @@ -# Google OAuth in Axum +# Axum with Google OAuth This template is an example of how you can implement Google OAuth using the Axum web framework in Rust. -## Prerequisites +## How to use this template Make sure you set up your Google OAuth, which you can find a link to set up [here.](https://console.cloud.google.com/apis/dashboard) diff --git a/axum/openai/README.md b/axum/openai/README.md index 776fbbdb..567e7c7d 100644 --- a/axum/openai/README.md +++ b/axum/openai/README.md @@ -1,5 +1,9 @@ +# Axum with OpenAI + A simple endpoint that sends a chat message to ChatGPT and returns the response. +## How to use this template + Set your OpenAI API key in `Secrets.toml`, then try it on a local run with: ```sh diff --git a/axum/postgres/README.md b/axum/postgres/README.md index cccd4458..e35075dc 100644 --- a/axum/postgres/README.md +++ b/axum/postgres/README.md @@ -1,8 +1,10 @@ -# Shuttle shared Postgres DB with Axum +# Axum with Shuttle Shared DB (Postgres) This template shows how to connect a Postgres database and use it for a simple TODO list app. -## Example usage +## How to use this template + +Run the project then try the following `curl` commands: ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todos --data '{"note":"My todo"}' diff --git a/axum/qdrant/README.md b/axum/qdrant/README.md index cf84257c..553ea073 100644 --- a/axum/qdrant/README.md +++ b/axum/qdrant/README.md @@ -1,8 +1,8 @@ -# Connect to a Qdrant Cloud DB from Shuttle +# Axum with Qdrant on Shuttle This example shows how to use `shuttle-qdrant` to connect to a Qdrant vector database from Shuttle. -## Prerequisites +## How to use this template Go to [Qdrant](https://qdrant.tech/) and start a database. Paste the URL and API key in the Secrets.toml file. diff --git a/axum/static-files/README.md b/axum/static-files/README.md index a8659eee..fe1caced 100644 --- a/axum/static-files/README.md +++ b/axum/static-files/README.md @@ -1,5 +1,9 @@ -# Serving Static Assets with Axum +# Axum with Static Assets This example shows how to serve static assets using [axum](https://github.com/tokio-rs/axum) and Shuttle. This example is inspired by the static-file-server example from the axum repo, to see more ways to do this check out the [original](https://github.com/tokio-rs/axum/blob/main/examples/static-file-server/src/main.rs). + +## Example usage + +Run the project and visit . diff --git a/axum/turso/README.md b/axum/turso/README.md index 2a9abddd..c84fd6da 100644 --- a/axum/turso/README.md +++ b/axum/turso/README.md @@ -1,6 +1,8 @@ +# Axum with Turso + An example that showcases using Turso with Axum and Shuttle. -## Example usage +## How to use this template Set your `TURSO_DB_TOKEN` in Secrets.toml and Turso database in `src/main.rs` in the annotation. diff --git a/axum/websocket/README.md b/axum/websocket/README.md index 4465be68..9b9dd024 100644 --- a/axum/websocket/README.md +++ b/axum/websocket/README.md @@ -1,5 +1,7 @@ +# Axum with Websockets + This template shows how to use websockets with Axum in a Shuttle project. -## Example usage +## How to use this template Run the project and visit to try it out. diff --git a/bevy/hello-world/README.md b/bevy/hello-world/README.md index 634df8b5..173770b8 100644 --- a/bevy/hello-world/README.md +++ b/bevy/hello-world/README.md @@ -1,6 +1,8 @@ +# Bevy on Shuttle (with Axum) + Example of how you can compile Bevy to WASM and run it on Shuttle. -## Instructions +## How to use this template Make sure you have `wasm-bindgen-cli` and the rustup `wasm32-unknown-unknown` compilation target added. If you don't, you can get them by running the following: ```bash diff --git a/custom-resource/pdo/README.md b/custom-resource/pdo/README.md index 8a9b8161..3c01b541 100644 --- a/custom-resource/pdo/README.md +++ b/custom-resource/pdo/README.md @@ -1,5 +1,7 @@ +# Custom Shuttle Resource + This template shows how to create your own custom Shuttle resource in a Shuttle project, using Axum for the `main.rs` file to set up the router. -## Example usage +## How to use this template Run the project and visit . diff --git a/custom-service/none/README.md b/custom-service/none/README.md index dd79e3ce..f066dd9c 100644 --- a/custom-service/none/README.md +++ b/custom-service/none/README.md @@ -1,6 +1,8 @@ +# Shuttle Custom Service + This template shows how to create your own custom Shuttle service that can run anything HTTP-based. -## Example usage +## How to use this template Set up whatever you want to do in the `bind()` function, then visit (or your relevant routes) to try it out. diff --git a/fullstack-templates/saas/README.md b/fullstack-templates/saas/README.md index be6310d5..e4f7fc60 100644 --- a/fullstack-templates/saas/README.md +++ b/fullstack-templates/saas/README.md @@ -21,7 +21,7 @@ users will be able to view their customers, sales records as well as some analyt - Typescript. - [cargo-shuttle](https://www.shuttle.rs) -## Instructions for Usage +## How to use this template - Initialize the template with: diff --git a/loco/hello-world/README.md b/loco/hello-world/README.md index 43915f96..4c9ed12e 100644 --- a/loco/hello-world/README.md +++ b/loco/hello-world/README.md @@ -14,10 +14,6 @@ Welcome to the [Loco](https://loco.rs) Hello World Shuttle Template, designed wi So see more Loco features, check out our [documentation website](https://loco.rs/docs/getting-started/tour/). -## Quick Start +## How to use this template -To launch your app, simply use the following command: - -```sh -shuttle run -``` +Run the project and visit . diff --git a/other/feature-flags/README.md b/other/feature-flags/README.md index 992429ac..0293f1a0 100644 --- a/other/feature-flags/README.md +++ b/other/feature-flags/README.md @@ -1,5 +1,7 @@ +# Cargo Feature Flags with Shuttle + An example that showcases how to use feature flags with Shuttle (see `Cargo.toml`). -## Example usage +## How to use this template Run the project and visit . diff --git a/other/standalone-binary/README.md b/other/standalone-binary/README.md index bdf1749f..cea07d14 100644 --- a/other/standalone-binary/README.md +++ b/other/standalone-binary/README.md @@ -8,3 +8,9 @@ All startup logic is placed in the binary source files, while the implementation - `src/bin/standalone.rs` is without Shuttle, run with `cargo run --bin standalone` (you can change the name) This example shows how to use separate logic for getting secrets (Shuttle secrets vs homemade solution), but the same approach can be applied to other resources that are initiated by Shuttle's main function. + +## How to use this template + +Run the project and visit . + +You can use `cargo run --bin standalone` to run the non-Shuttle binary. diff --git a/poem/hello-world/README.md b/poem/hello-world/README.md index 7305bd21..a7bd5bfc 100644 --- a/poem/hello-world/README.md +++ b/poem/hello-world/README.md @@ -1,5 +1,7 @@ -An example that showcases using the `poem` web service framework with Shuttle. +# Poem Hello World -## Example usage +An example that showcases using the `poem` web service framework with shuttle. + +## How to use this template Run the project and visit . diff --git a/poise/hello-world/README.md b/poise/hello-world/README.md index 2b5f36d9..fb7cebbe 100644 --- a/poise/hello-world/README.md +++ b/poise/hello-world/README.md @@ -2,6 +2,8 @@ In this example we will deploy a Poise/Serenity bot with Shuttle that responds to the `/hello` command with `world!`. To run this bot we need a valid Discord Token. To get started log in to the [Discord developer portal](https://discord.com/developers/applications). +## How to use this template + 1. Click the New Application button, name your application and click Create. 2. Navigate to the Bot tab in the lefthand menu, and add a new bot. 3. On the bot page click the Reset Token button to reveal your token. Put this token in your `Secrets.toml`. It's very important that you don't reveal your token to anyone, as it can be abused. Create a `.gitignore` file to omit your `Secrets.toml` from version control. diff --git a/rocket/dyn-templates/README.md b/rocket/dyn-templates/README.md index 58b00112..712339f3 100644 --- a/rocket/dyn-templates/README.md +++ b/rocket/dyn-templates/README.md @@ -1,5 +1,9 @@ -# Rendering Handlebars dynamic templates with Rocket +# Rocket with dynamic templates using Handlebars This example shows how to render templated content using Handlebars templates from [rocket](https://github.com/SergioBenitez/Rocket/) and shuttle. This example is inspired by templating example from the rocket repo, to see more ways to do this checkout the [original](https://github.com/SergioBenitez/Rocket/tree/master/examples/templating). + +## How to use + +Run the project and visit . diff --git a/rocket/hello-world/README.md b/rocket/hello-world/README.md index 2f2f92a9..9c5f1d49 100644 --- a/rocket/hello-world/README.md +++ b/rocket/hello-world/README.md @@ -1,5 +1,7 @@ +# Rocket Hello World + An example that showcases using the `rocket` web service framework with Shuttle. -## Example usage +## How to use this template Run the project and visit . diff --git a/rocket/jwt-authentication/README.md b/rocket/jwt-authentication/README.md index 9fa918fd..775a8e0d 100644 --- a/rocket/jwt-authentication/README.md +++ b/rocket/jwt-authentication/README.md @@ -1,4 +1,4 @@ -# Issue and verify JWT for authentication +# Rocket with JWT authentication This example shows how to use [Rocket request guards](https://rocket.rs/v0.5-rc/guide/requests/#request-guards) for authentication with [JSON Web Tokens](https://jwt.io/) (JWT for short). The idea is that all requests authenticate first at to get a JWT. @@ -35,7 +35,7 @@ shuttle deploy Now make a note of the `Host` for the deploy to use in the examples below. Or just use `authentication-rocket-app.shuttleapp.rs` as the host below. -### Seeing it in action +## How to use this template First, we should be able to access the public endpoint without any authentication using: diff --git a/rocket/opendal-memory/README.md b/rocket/opendal-memory/README.md index 06a36220..0d9605ec 100644 --- a/rocket/opendal-memory/README.md +++ b/rocket/opendal-memory/README.md @@ -8,3 +8,12 @@ The project consists of the following files - `Shuttle.toml` contains the name of the app - `src/main.rs` is where all the magic happens - it creates a Shuttle service with two endpoints: one for adding new data and one for retrieving it back. + +## How to use this template + +Run the project, then try out the following `curl` command: + +```bash +curl -X POST -H 'content-type: application/json' localhost:8000/todo --data '{"note":"My todo"}' +# {"id":1,"note":"My todo"} +``` diff --git a/rocket/postgres/README.md b/rocket/postgres/README.md index 03b20c60..1d9f0a85 100644 --- a/rocket/postgres/README.md +++ b/rocket/postgres/README.md @@ -1,8 +1,10 @@ -# Shuttle shared Postgres DB with Rocket +# Rocket with Shuttle Shared DB (Postgres) This template shows how to connect a Postgres database and use it for a simple TODO list app. -## Example usage +## How to use this template + +Run the project then try the following `curl` commands: ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todo --data '{"note":"My todo"}' diff --git a/rocket/secrets/README.md b/rocket/secrets/README.md index 988cbb6c..5db77390 100644 --- a/rocket/secrets/README.md +++ b/rocket/secrets/README.md @@ -1,5 +1,12 @@ -## How to use +## Using Shuttle Secrets with Rocket + +This example shows how to use secrets using [rocket](https://github.com/rwf2/rocket) and Shuttle. + The secrets resource requires a `Secrets.toml` file to be present in your crate. Each like in this file should be a key-value pair that you can access using `SecretStore::get(&self, key)`. +## How to use + Rename `Secrets.toml.example` to `Secrets.toml` to use this example. + +Once done, run the example and visit . diff --git a/rocket/static-files/README.md b/rocket/static-files/README.md index 0e633aec..78fcc0a1 100644 --- a/rocket/static-files/README.md +++ b/rocket/static-files/README.md @@ -1,3 +1,7 @@ -# Serving Static Assets with Rocket +## Serving Static Assets with Rocket This example shows how to serve static assets using [rocket](https://github.com/rwf2/rocket) and Shuttle. + +## Example usage + +Run the project and visit . diff --git a/rocket/url-shortener/README.md b/rocket/url-shortener/README.md index 708beff5..209e3f14 100644 --- a/rocket/url-shortener/README.md +++ b/rocket/url-shortener/README.md @@ -1,8 +1,8 @@ -# Url Shortener +# Rocket URL Shortener A URL shortener that you can use from your terminal - built with shuttle, rocket and postgres/sqlx. -## How to use it +## How to use this template You can use this URL shortener directly from your terminal. Just copy and paste this command to your terminal and replace `` with the URL that you want to shorten diff --git a/rocket/workspace/README.md b/rocket/workspace/README.md index aeb20d6c..ff03961a 100644 --- a/rocket/workspace/README.md +++ b/rocket/workspace/README.md @@ -1,5 +1,6 @@ +# Rocket with Cargo Workspaces This example shows how to use a Cargo workspace with Shuttle using the `rocket` web service frameowrk. -## Example usage +## How to use this template Run the project and visit . diff --git a/salvo/hello-world/README.md b/salvo/hello-world/README.md index 64afac27..fe8efdff 100644 --- a/salvo/hello-world/README.md +++ b/salvo/hello-world/README.md @@ -1,5 +1,7 @@ +# Salvo Hello World + An example that showcases using the `salvo` web service framework with Shuttle. -## Example usage +## How to use this template Run the project and visit . diff --git a/salvo/image-rescaler/README.md b/salvo/image-rescaler/README.md index 25270691..b1fae7f8 100644 --- a/salvo/image-rescaler/README.md +++ b/salvo/image-rescaler/README.md @@ -1,5 +1,7 @@ -# Image rescaler +# Salvo image rescaler This is a simple example showing how to use path parameters in Salvo and the `image` crate to load and manipulate an image. +## How to use this template + Running the project and going to `/400/400` returns the Shuttle logo image but rescaled to 400 x 400 pixels. diff --git a/serenity/hello-world/README.md b/serenity/hello-world/README.md index 086084e4..ee219b3f 100644 --- a/serenity/hello-world/README.md +++ b/serenity/hello-world/README.md @@ -2,6 +2,8 @@ In this example we will deploy a Serenity bot with Shuttle that responds to the `!hello` command with `world!`. To run this bot we need a valid Discord Token. To get started log in to the [Discord developer portal](https://discord.com/developers/applications). +## How to use this template + 1. Click the New Application button, name your application and click Create. 2. Navigate to the Bot tab in the lefthand menu, and add a new bot. 3. On the bot page click the Reset Token button to reveal your token. Put this token in your `Secrets.toml`. It's very important that you don't reveal your token to anyone, as it can be abused. Create a `.gitignore` file to omit your `Secrets.toml` from version control. diff --git a/serenity/postgres/README.md b/serenity/postgres/README.md index 271d3ee8..7e912b85 100644 --- a/serenity/postgres/README.md +++ b/serenity/postgres/README.md @@ -2,6 +2,8 @@ In this example we will deploy a Serenity bot with Shuttle that can add, list and complete todos using [Application Commands](https://discord.com/developers/docs/interactions/application-commands). To persist the todos we need a database. We will have Shuttle provison a PostgreSQL database for us by enabling the `sqlx-postgres` feature for `shuttle-service` and passing `#[shared::Postgres] pool: PgPool` as an argument to our `main` function. +## How to use this template + To run this bot we need a valid Discord Token. To get started log in to the [Discord developer portal](https://discord.com/developers/applications). 1. Click the New Application button, name your application and click Create. diff --git a/serenity/weather-forecast/README.md b/serenity/weather-forecast/README.md index 34b9de58..d25e61f3 100644 --- a/serenity/weather-forecast/README.md +++ b/serenity/weather-forecast/README.md @@ -1,3 +1,7 @@ # Serenity Weather Forecast Bot with Shuttle +A Discord bot created with Serenity that can get the weather forecast. + +## How to use this template + For a full tutorial on how to build and set up this bot, please refer to [Shuttle docs](https://docs.shuttle.rs/templates/tutorials/discord-weather-forecast) diff --git a/shuttle-cron/README.md b/shuttle-cron/README.md index 2677ff2f..8b64b737 100644 --- a/shuttle-cron/README.md +++ b/shuttle-cron/README.md @@ -8,7 +8,8 @@ When the cron job is called, the data is grabbed from the `JobContext` and we th The actual function to be ran itself is stored in `job_fn()` in the main function, as a function pointer. -# Usage +## How to use this template + Run `shuttle run` to spin up the service locally. You can change the behavior of the cronjob by editing the `execute()` function for `CronjobData`. diff --git a/thruster/hello-world/README.md b/thruster/hello-world/README.md index 40cc4396..c9b7b5f2 100644 --- a/thruster/hello-world/README.md +++ b/thruster/hello-world/README.md @@ -1,5 +1,7 @@ +# Thruster Hello World + An example that showcases using the `thruster` web service framework with Shuttle. -## Example usage +## How to use this template Run the project and visit . diff --git a/tide/hello-world/README.md b/tide/hello-world/README.md index 4e35b652..9f157f1c 100644 --- a/tide/hello-world/README.md +++ b/tide/hello-world/README.md @@ -1,5 +1,7 @@ +# Tide Hello World + An example that showcases using the `tide` web service framework with Shuttle. -## Example usage +## How to use this template Run the project and visit . diff --git a/tower/hello-world/README.md b/tower/hello-world/README.md index f350a502..50e1b68d 100644 --- a/tower/hello-world/README.md +++ b/tower/hello-world/README.md @@ -1,3 +1,5 @@ +# Tower Hello World + An example that showcases using the `tower` web service framework (with `hyper`) with Shuttle. ## Example usage diff --git a/tracing/custom-tracing-subscriber/README.md b/tracing/custom-tracing-subscriber/README.md index 0c683a97..16bf1d0a 100644 --- a/tracing/custom-tracing-subscriber/README.md +++ b/tracing/custom-tracing-subscriber/README.md @@ -1,9 +1,11 @@ +# Custom Tracing Subscriber with Shuttle + An example that showcases using a custom `tracing-subscriber` with Shuttle. Notes: - `default-features` is disabled on `shuttle-runtime` crate to allow this to be possible -## Example usage +## How to use this template Run the project and visit . diff --git a/warp/hello-world/README.md b/warp/hello-world/README.md index 3051701d..d4a9accf 100644 --- a/warp/hello-world/README.md +++ b/warp/hello-world/README.md @@ -1,5 +1,7 @@ +# Warp Hello World + An example that showcases using the `warp` web service framework (with `hyper`) with Shuttle. -## Example usage +## How to use this template Run the project and visit . From 8e790ed807ddc848fe0a50c10458100dfe39973e Mon Sep 17 00:00:00 2001 From: Joshua Mo Date: Thu, 24 Oct 2024 18:45:26 +0100 Subject: [PATCH 5/6] feat: standardize every last readme ever --- README.md | 2 +- actix-web/clerk/README.md | 25 ++++++++-- actix-web/cookie-authentication/README.md | 24 +++++++++- actix-web/hello-world/README.md | 21 ++++++++- actix-web/postgres/README.md | 23 ++++++++- actix-web/static-files/README.md | 25 +++++++++- actix-web/websocket-actorless/README.md | 22 ++++++++- actix-web/websocket-actorless/src/main.rs | 2 +- axum/hello-world/README.md | 21 ++++++++- axum/htmx-crud/README.md | 21 +++++++++ axum/jwt-authentication/README.md | 23 ++++++++- axum/metadata/README.md | 21 ++++++++- axum/oauth2/README.md | 24 +++++++++- axum/openai/README.md | 26 ++++++++++- axum/postgres/README.md | 25 +++++++++- axum/qdrant/README.md | 25 +++++++++- axum/static-files/README.md | 23 ++++++++- axum/static-files/assets/index.html | 2 +- axum/turso/README.md | 22 ++++++++- axum/websocket/README.md | 20 +++++++- axum/websocket/src/main.rs | 2 +- bevy/hello-world/README.md | 20 ++++++++ custom-resource/pdo/README.md | 26 ++++++++++- custom-service/none/README.md | 22 ++++++++- custom-service/request-scheduler/README.md | 31 ++++++++++--- fullstack-templates/saas/README.md | 43 ++++++----------- fullstack-templates/saas/src/pages/index.tsx | 4 +- loco/hello-world/Cargo.toml | 2 +- loco/hello-world/README.md | 29 ++++++++++-- other/feature-flags/README.md | 22 ++++++++- other/standalone-binary/Cargo.toml | 2 +- other/standalone-binary/README.md | 25 +++++++++- poem/hello-world/README.md | 22 ++++++++- poise/hello-world/README.md | 24 +++++++++- rocket/dyn-templates/README.md | 23 ++++++++- rocket/hello-world/README.md | 21 ++++++++- rocket/jwt-authentication/README.md | 49 +++++++++----------- rocket/opendal-memory/README.md | 23 +++++++-- rocket/postgres/README.md | 24 +++++++++- rocket/secrets/README.md | 25 ++++++++-- rocket/static-files/README.md | 23 ++++++++- rocket/url-shortener/README.md | 27 ++++++++--- rocket/workspace/README.md | 24 +++++++++- salvo/hello-world/README.md | 22 ++++++++- salvo/image-rescaler/README.md | 22 ++++++++- serenity/hello-world/README.md | 24 ++++++++++ serenity/postgres/README.md | 29 ++++++++++-- serenity/weather-forecast/README.md | 22 ++++++++- shuttle-cron/README.md | 20 ++++++++ thruster/hello-world/README.md | 22 ++++++++- tide/hello-world/README.md | 22 ++++++++- tower/hello-world/README.md | 24 +++++++++- tracing/custom-tracing-subscriber/README.md | 21 ++++++++- warp/hello-world/README.md | 24 +++++++++- 54 files changed, 1021 insertions(+), 141 deletions(-) diff --git a/README.md b/README.md index f029664b..86cd5bad 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The examples in this repository, consists of *"Hello, world!"* examples of all o ## How to clone, run and deploy an example -To clone an example, use the `init` command of the [`cargo-shuttle`](https://docs.shuttle.rs/introduction/installation) CLI and specify the git URL and optional subfolder: +To clone an example, use the `init` command of the [`cargo-shuttle`](https://docs.shuttle.dev/introduction/installation) CLI and specify the git URL and optional subfolder: ```bash shuttle init --from https://github.com/shuttle-hq/shuttle-examples --subfolder axum/hello-world diff --git a/actix-web/clerk/README.md b/actix-web/clerk/README.md index e66de052..674f63ba 100644 --- a/actix-web/clerk/README.md +++ b/actix-web/clerk/README.md @@ -1,14 +1,28 @@ # Actix Web with Clerk auth +## Introduction + This template uses Actix-web and the clerk-rs crate for providing authentication from Clerk in the backend. The frontend is a simple React app that uses Clerk's React components. The template simply shows a list of all signed up users after you sign in, but it can be extended to create a full app with authenticated endpoints. +## Features + +- Authentication backed by Clerk +- React-based frontend (with Clerk React components) + +## Pre-requisites + +- Rust +- Node.js/NPM. +- Typescript. +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Sign up at clerk.com, go to the dashboard and create an application with the sign-in options you prefer. +Sign up at [https://clerk.com](https://clerk.com), then go to the dashboard and create an application with the sign-in options you prefer. Get the `CLERK_SECRET_KEY` secret and put it in `backend/Secrets.toml`. Make sure you don't commit this file. @@ -18,10 +32,15 @@ Get the `VITE_CLERK_PUBLISHABLE_KEY` secret and put it in `frontend/.env`. > The frontend was initialized from the React+TS template in `npm create vite@latest`. > The Clerk components were then added by following the guide at . -cd into the frontend and run `npm install` and `npm run build`. This builds the frontend assets and places them in `frontend/dist`. +`cd` into the frontend and run `npm install` and `npm run build`. This builds the frontend assets and places them in `frontend/dist`. cd back to the root and run `shuttle run`. The backend serves the web page from the dist folder, and an auth-protected API that fetches the list of all users that have signed up so far. -You can then do `shuttle deploy`, but consider switching to a production key from Clerk. +Once you're ready to deploy, use `shuttle deploy`. You may want to consider switching to a production key from Clerk if you aren't using one already. The development key can still be used in `Secrets.dev.toml`. + +## Troubleshooting +- If connecting to Clerk doesn't work, try checking your Secrets.toml file. +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/actix-web/cookie-authentication/README.md b/actix-web/cookie-authentication/README.md index 9e7e5773..30104437 100644 --- a/actix-web/cookie-authentication/README.md +++ b/actix-web/cookie-authentication/README.md @@ -1,9 +1,29 @@ # Actix Web Cookie authentication with actix-session +## Introduction + This template uses the [actix_identity](https://docs.rs/actix-identity) and [actix_session](https://docs.rs/actix-session) crates to manage user sessions. -## How to use +## Features + +- (basic) User-based session management +- Private/public routing + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) -Running the project and visiting will show the currently logged in user. +## How to use this template + +Run the project with `shuttle run`. + +Visiting will show the currently logged in user. Visiting will log you in as `user1` (no authentication logic is in place). Visiting will log you out again. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/actix-web/hello-world/README.md b/actix-web/hello-world/README.md index 2d61d499..c466e765 100644 --- a/actix-web/hello-world/README.md +++ b/actix-web/hello-world/README.md @@ -1,7 +1,26 @@ # Actix Web Hello World +## Introduction + A `Hello world!` example for using Actix Web with Shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the app and go to . +Run the project with `shuttle run`. + +Visiting should output `Hello, world!`. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/actix-web/postgres/README.md b/actix-web/postgres/README.md index 972195f8..c00d6792 100644 --- a/actix-web/postgres/README.md +++ b/actix-web/postgres/README.md @@ -1,10 +1,22 @@ # Actix Web with Shuttle Shared DB (Postgres) +## Introduction + This template shows how to connect a Postgres database and use it for a simple TODO list app. -## How to use this template: +## Features +- Public routes for creating/fetching notes using a database. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template -Run the project then run the following `curl` commands below: +Run the project with `shuttle run`. + +Then run the following `curl` commands below: ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todos --data '{"note":"My todo"}' @@ -13,3 +25,10 @@ curl -X POST -H 'content-type: application/json' localhost:8000/todos --data '{" curl localhost:8000/todos/1 # {"id":1,"note":"My todo"} ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're running locally, don't forget to have Docker installed and running! diff --git a/actix-web/static-files/README.md b/actix-web/static-files/README.md index 1190ccef..3958f568 100644 --- a/actix-web/static-files/README.md +++ b/actix-web/static-files/README.md @@ -1,10 +1,31 @@ -## Actix Web Static Files +# Actix Web Static Files + +## Introduction This template uses `actix_files` to serve the files in the `assets` directory. -## Example usage +## Features + +- Plain HTML-based frontend + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run the project with `shuttle run`. + +Then run the following `curl` command below (or visit ): ```bash curl localhost:8000/index.html #

Hello world!

``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/actix-web/websocket-actorless/README.md b/actix-web/websocket-actorless/README.md index b6df6f32..41879783 100644 --- a/actix-web/websocket-actorless/README.md +++ b/actix-web/websocket-actorless/README.md @@ -1,7 +1,27 @@ # Actix Web Actorless Websockets +## Introduction + This template shows how to use actorless websockets to build an API monitoring service and a simple chat app. +## Features + +- A plain HTML-based frontend +- Websocket connection + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the app and go to . +Run the project with `shuttle run`. + +Then visit to try it out! + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/actix-web/websocket-actorless/src/main.rs b/actix-web/websocket-actorless/src/main.rs index 173ff3b3..9f66d167 100644 --- a/actix-web/websocket-actorless/src/main.rs +++ b/actix-web/websocket-actorless/src/main.rs @@ -15,7 +15,7 @@ use std::{ use tokio::sync::{mpsc, watch}; const PAUSE_SECS: u64 = 15; -const STATUS_URI: &str = "https://api.shuttle.rs"; +const STATUS_URI: &str = "https://api.shuttle.dev"; type AppState = ( mpsc::UnboundedSender, diff --git a/axum/hello-world/README.md b/axum/hello-world/README.md index f06be717..57b26100 100644 --- a/axum/hello-world/README.md +++ b/axum/hello-world/README.md @@ -1,7 +1,26 @@ # Axum Hello World +## Introduction + A `Hello world!` example for using Axum with Shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the app and go to . +Run the project with `shuttle run`. + +Visiting should output `Hello, world!`. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/htmx-crud/README.md b/axum/htmx-crud/README.md index b8842d18..9fea020b 100644 --- a/axum/htmx-crud/README.md +++ b/axum/htmx-crud/README.md @@ -1,9 +1,30 @@ # Axum with HTMx +## Introduction + This is an example of how you can use Shuttle with Axum, Askama and htmx to create a frontend that's easily extendable and requires zero framework knowledge, while being able to easily inject variables from the backend into the frontend. The app is a TODO list with a main page and an event stream page. +## Features + +- A templating-based HTML frontend +- Routes for creating/viewing todos +- A route for viewing a real-time stream of todo list changes + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template +Run the project with `shuttle run`. + Run the app and go to to add and remove TODOs from the list. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/jwt-authentication/README.md b/axum/jwt-authentication/README.md index c43d7aba..799443ba 100644 --- a/axum/jwt-authentication/README.md +++ b/axum/jwt-authentication/README.md @@ -1,7 +1,26 @@ # Axum JWT authentication +## Introduction + This template uses the `jsonwebtoken` crate to encode and decode claims in a JWT, which clients use in the Authorization HTTP header to access protected resources (endpoints). -## Example usage +## Features + +- JWT based authentication + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run the project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. -Run the app and go to . +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/metadata/README.md b/axum/metadata/README.md index 24206b5a..e05e1bf5 100644 --- a/axum/metadata/README.md +++ b/axum/metadata/README.md @@ -1,7 +1,26 @@ # Axum with Shuttle metadata +## Introduction + An example that showcases Shuttle metadata at the base route using Axum. +## Features + +- View Shuttle metadata about your project at the base route + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the app and go to . +Run the project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/oauth2/README.md b/axum/oauth2/README.md index f044b768..a6f19918 100644 --- a/axum/oauth2/README.md +++ b/axum/oauth2/README.md @@ -1,16 +1,36 @@ # Axum with Google OAuth +## Introduction + This template is an example of how you can implement Google OAuth using the Axum web framework in Rust. +## Features + +- Google-based Oauth2 authentication + +## Pre-requisites + +- Rust +- Google account +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template Make sure you set up your Google OAuth, which you can find a link to set up [here.](https://console.cloud.google.com/apis/dashboard) -Set your secrets in the Secrets.toml file: +Set your secrets in a `Secrets.toml` file: ```toml GOOGLE_OAUTH_CLIENT_ID = "your-client-id" GOOGLE_OAUTH_CLIENT_SECRET = "your-client-secret" ``` -Use `shuttle run` and visit `http://localhost:8000` once the app is running, then try it out! +Run the project with `shuttle run`. + +Visit `http://localhost:8000` once the app is running, then try it out! + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/openai/README.md b/axum/openai/README.md index 567e7c7d..b4d5474a 100644 --- a/axum/openai/README.md +++ b/axum/openai/README.md @@ -1,11 +1,33 @@ # Axum with OpenAI +## Introduction + A simple endpoint that sends a chat message to ChatGPT and returns the response. +## Features + +- Query an OpenAI model at the base route + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Set your OpenAI API key in `Secrets.toml`, then try it on a local run with: +Set your OpenAI API key in `Secrets.toml`. + +Run the project with `shuttle run`. + +Try the following `curl` command to query OpenAI: ```sh -curl http://localhost:8000 -H 'content-type: application/json' --data '{"message":"What is shuttle.rs?"}' +curl http://localhost:8000 -H 'content-type: application/json' --data '{"message":"What is shuttle.dev?"}' ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If connecting to OpenAI doesn't work, try checking your Secrets.toml file. diff --git a/axum/postgres/README.md b/axum/postgres/README.md index e35075dc..f592d6ce 100644 --- a/axum/postgres/README.md +++ b/axum/postgres/README.md @@ -1,10 +1,25 @@ # Axum with Shuttle Shared DB (Postgres) +## Introduction + This template shows how to connect a Postgres database and use it for a simple TODO list app. +## Features + +- Public routes for fetching/creating notes using a database. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project then try the following `curl` commands: +Set your OpenAI API key in `Secrets.toml`. + +Run the project with `shuttle run`. + +Try the following `curl` commands to interact with your database through the API: ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todos --data '{"note":"My todo"}' @@ -13,3 +28,11 @@ curl -X POST -H 'content-type: application/json' localhost:8000/todos --data '{" curl localhost:8000/todos/1 # {"id":1,"note":"My todo"} ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If connecting to OpenAI doesn't work, try checking your Secrets.toml file. +- Make sure you have Docker installed and running. diff --git a/axum/qdrant/README.md b/axum/qdrant/README.md index 553ea073..8d099206 100644 --- a/axum/qdrant/README.md +++ b/axum/qdrant/README.md @@ -1,8 +1,31 @@ # Axum with Qdrant on Shuttle +## Introduction + This example shows how to use `shuttle-qdrant` to connect to a Qdrant vector database from Shuttle. +## Features + +- View your Qdrant collections at the base route + +## Pre-requisites + +- Rust +- Qdrant user account +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Go to [Qdrant](https://qdrant.tech/) and start a database. +Go to [Qdrant](https://qdrant.tech/) and start a database and collection. Paste the URL and API key in the Secrets.toml file. + +Run the project with `shuttle run`. + +Visit to view your collections. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If connecting to Qdrant doesn't work, try checking your Secrets.toml file. diff --git a/axum/static-files/README.md b/axum/static-files/README.md index fe1caced..3d2179bc 100644 --- a/axum/static-files/README.md +++ b/axum/static-files/README.md @@ -1,9 +1,28 @@ # Axum with Static Assets +## Introduction + This example shows how to serve static assets using [axum](https://github.com/tokio-rs/axum) and Shuttle. This example is inspired by the static-file-server example from the axum repo, to see more ways to do this check out the [original](https://github.com/tokio-rs/axum/blob/main/examples/static-file-server/src/main.rs). -## Example usage +## Features + +- Plain HTML-based frontend + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run the project with `shuttle run`. + +Visit to view the homepage. + +Once you're ready to deploy, use `shuttle deploy`. -Run the project and visit . +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/static-files/assets/index.html b/axum/static-files/assets/index.html index 42f4d4e4..2ee2eb56 100644 --- a/axum/static-files/assets/index.html +++ b/axum/static-files/assets/index.html @@ -7,7 +7,7 @@
-

Axum static file server on Shuttle

+

Axum static file server on Shuttle

This is an example of serving static HTML, CSS, and JS files with Axum and running it with Shuttle.

diff --git a/axum/turso/README.md b/axum/turso/README.md index c84fd6da..8fe173b6 100644 --- a/axum/turso/README.md +++ b/axum/turso/README.md @@ -1,13 +1,33 @@ # Axum with Turso +## Introduction + An example that showcases using Turso with Axum and Shuttle. +## Features + +- Use Turso to store and retrieve database records. + +## Pre-requisites + +- Rust +- Turso user account +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template Set your `TURSO_DB_TOKEN` in Secrets.toml and Turso database in `src/main.rs` in the annotation. -Run the app, then try it out with the following `curl` command: +Run the project with `shuttle run`. + +Then try it out with the following `curl` command: ```sh curl http://localhost:8000 -H 'content-type: application/json' --data '{"uid":"1","email":"foo@bar.xyz"}' ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/websocket/README.md b/axum/websocket/README.md index 9b9dd024..b0917584 100644 --- a/axum/websocket/README.md +++ b/axum/websocket/README.md @@ -2,6 +2,24 @@ This template shows how to use websockets with Axum in a Shuttle project. +## Features + +- Plain HTML-based frontend +- Websocket connection + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit to try it out. +Run the project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/axum/websocket/src/main.rs b/axum/websocket/src/main.rs index 2c6ad0ba..5c00c1f9 100644 --- a/axum/websocket/src/main.rs +++ b/axum/websocket/src/main.rs @@ -25,7 +25,7 @@ struct State { } const PAUSE_SECS: u64 = 15; -const STATUS_URI: &str = "https://api.shuttle.rs"; +const STATUS_URI: &str = "https://api.shuttle.dev"; #[derive(Serialize)] struct Response { diff --git a/bevy/hello-world/README.md b/bevy/hello-world/README.md index 173770b8..acbfeef4 100644 --- a/bevy/hello-world/README.md +++ b/bevy/hello-world/README.md @@ -1,7 +1,20 @@ # Bevy on Shuttle (with Axum) +## Introduction + Example of how you can compile Bevy to WASM and run it on Shuttle. +## Features + +- A Bevy program that prints `Hello, world!`. +- A server that runs the WASM-compiled Bevy program. + +## Pre-requisites + +- Rust +- [Bevy dependencies](https://github.com/bevyengine/bevy/blob/main/docs/linux_dependencies.md) +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template Make sure you have `wasm-bindgen-cli` and the rustup `wasm32-unknown-unknown` compilation target added. If you don't, you can get them by running the following: @@ -20,3 +33,10 @@ make build ``` Go to the project workspace root or the `server` folder, run `shuttle run`, then visit `http://localhost:8000/game`, you should see your Bevy program in action! + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- Don't forget to install Bevy dependencies (as above) if you get compilation errors. diff --git a/custom-resource/pdo/README.md b/custom-resource/pdo/README.md index 3c01b541..b6d9063c 100644 --- a/custom-resource/pdo/README.md +++ b/custom-resource/pdo/README.md @@ -1,7 +1,29 @@ # Custom Shuttle Resource -This template shows how to create your own custom Shuttle resource in a Shuttle project, using Axum for the `main.rs` file to set up the router. +## Introduction + +This template shows how to create your own custom Shuttle resource in a Shuttle project, using Axum for the `main.rs` file to set up the route. + +Note that PDO is short for Plain Data Object. + +## Features + +- A `lib.rs` file that contains code for a custom Shuttle resource +- A `main.rs` file that uses the + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) ## How to use this template -Run the project and visit . +Run the project using `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/custom-service/none/README.md b/custom-service/none/README.md index f066dd9c..ba2be37e 100644 --- a/custom-service/none/README.md +++ b/custom-service/none/README.md @@ -1,9 +1,29 @@ # Shuttle Custom Service +## Introduction + This template shows how to create your own custom Shuttle service that can run anything HTTP-based. +## Features + +- A struct that implements `shuttle_runtime::Service`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Set up whatever you want to do in the `bind()` function, then visit (or your relevant routes) to try it out. +Set up whatever you want to do in the `bind()` function, then run the project using `shuttle run`. + +Visit (or your relevant routes) to try it out. Variables from resource annotations can be added to `MyService` struct to use them in the `bind()` function. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- Note that by default the service doesn't do anything. You need to run a server or do something else that runs in an infinite loop otherwise the program will exit. diff --git a/custom-service/request-scheduler/README.md b/custom-service/request-scheduler/README.md index 5f90e955..a7eab1c4 100644 --- a/custom-service/request-scheduler/README.md +++ b/custom-service/request-scheduler/README.md @@ -1,21 +1,34 @@ # request-scheduler +## Introduction + A service that calls URLs at specified cron-style intervals. The service exposes a `/crontab/set` endpoint that accepts a schedule and a URL -as form data and persists jobs with `shuttle_persist` between runs, e.g. it will +as form data and persists jobs with `shuttle_persist` between runs, e.g. it will pick up existing jobs after being restarted. Internally, `CrontabService` implements a custom service with -[`shuttle_runtime::Service`](https://docs.shuttle.rs/examples/custom-service), -uses [`shuttle_persist`](https://docs.shuttle.rs/resources/shuttle-persist), -and sets up an [`axum::Server`](https://github.com/tokio-rs/axum) that sends +[`shuttle_runtime::Service`](https://docs.shuttle.dev/examples/custom-service), +uses [`shuttle_persist`](https://docs.shuttle.dev/resources/shuttle-persist), +and sets up an [`axum::Server`](https://github.com/tokio-rs/axum) that sends jobs to a `CronRunner`. -# Usage +## Features + +- An endpoint for adding cronjobs +- Run cronjobs + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + Run `shuttle run` to spin up the service locally. -Fire a POST request to the `set-schedule` URL to create a new cron job. Use +Fire a POST request to the `set-schedule` URL to create a new cron job. Use the provided `request.sh` for a quick example or the below snippet: ``` @@ -23,3 +36,9 @@ curl -v http://localhost:8000/crontab/set\ -H "Content-Type: application/x-www-form-urlencoded"\ -d "schedule='*/2 * * * * *'&url='http://localhost:8000/trigger-me'" ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/fullstack-templates/saas/README.md b/fullstack-templates/saas/README.md index e4f7fc60..10cef822 100644 --- a/fullstack-templates/saas/README.md +++ b/fullstack-templates/saas/README.md @@ -13,46 +13,31 @@ users will be able to view their customers, sales records as well as some analyt - Mailgun (email subscription, welcome email etc) - Pre-configured frontend routes for easy transition - Examples of how to implement simple dashboard analytics +- Uses `turbowatch` for live reloads (with `npm run dev`) +- Bundle analysis with `npm run analyze` + +![Main page for Next.js + Shuttle Saas Template](./Mainpage.png) ## Pre-requisites - Rust -- Node.js/NPM. -- Typescript. -- [cargo-shuttle](https://www.shuttle.rs) +- Node.js/NPM +- Typescript +- Docker if running locally +- [Mailgun API key](https://www.mailgun.com) +- [Stripe API key](https://stripe.com) +- [cargo-shuttle](https://www.shuttle.dev) ## How to use this template -- Initialize the template with: - - ```sh - shuttle init --from shuttle-hq/shuttle-examples --subfolder fullstack-templates/saas - ``` +Run `npm i` to install the dependencies on the frontend. -- cd into the folder -- Run `npm i` to install the dependencies on the frontend. -- Set your secrets in the Secrets.toml file at the `Cargo.toml` level of your backend folder. Unset secrets will default +Set your secrets in the Secrets.toml file at the `Cargo.toml` level of your backend folder. Unset secrets will default to "None" to prevent automatic crashing of the web service, but some services may not work. -## Development Scripts +Use `npm run dev` and visit to try it out. -- **Using `dev` for Development:** - - Run `npm run dev` to start your application with live reload capabilities. This script uses `turbowatch` to - monitor changes in both the frontend and backend. - - Visit [http://localhost:8000](http://localhost:8000) once the app has built. - - If you prefer using `cargo-watch` instead of `turbowatch`, the watch feature can be disabled in - the `turbowatch.ts` file. -- **Frontend-Focused Development with `next-dev`:** - - For a frontend-specific development workflow, use `npm run next-dev`. - - This script runs Next.js in a development mode optimized for faster builds and reloads, enhancing your frontend - development experience. -- **Analyzing Bundle Size with `analyze`:** - - The `analyze` script is designed to provide insights into the bundle size of your Next.js application. - - Run `npm run analyze` to generate a detailed report of the size of each component and dependency in your bundle. - - This is particularly useful for identifying large dependencies or components that could be optimized for better - performance. - -![Main page for Next.js + Shuttle Saas Template](./Mainpage.png) +When you're ready to deploy, use `npm run deploy` which will build the static assets then deploy the service. ## Troubleshooting diff --git a/fullstack-templates/saas/src/pages/index.tsx b/fullstack-templates/saas/src/pages/index.tsx index d97fd83c..202183dc 100644 --- a/fullstack-templates/saas/src/pages/index.tsx +++ b/fullstack-templates/saas/src/pages/index.tsx @@ -5,7 +5,7 @@ const cards = [ { title: 'Deployed from Shuttle', description: 'Deployed via Shuttle, a Rust-native cloud dev platform.', - href: 'https://www.shuttle.rs', + href: 'https://www.shuttle.dev', }, { title: 'Learn About Rust', @@ -50,7 +50,7 @@ export default function Home() {

Powered by{' '} - + 🚀 Shuttle

diff --git a/loco/hello-world/Cargo.toml b/loco/hello-world/Cargo.toml index 31a33af2..7b1a5878 100644 --- a/loco/hello-world/Cargo.toml +++ b/loco/hello-world/Cargo.toml @@ -27,7 +27,7 @@ required-features = [] [[bin]] name = "hello_world" -path = "src/bin/shuttle.rs" +path = "src/bin/shuttle.dev" [dev-dependencies] serial_test = "*" diff --git a/loco/hello-world/README.md b/loco/hello-world/README.md index 4c9ed12e..906809bd 100644 --- a/loco/hello-world/README.md +++ b/loco/hello-world/README.md @@ -1,9 +1,12 @@ -# Shuttle Loco template :train: +# Shuttle Loco template + +## Introduction Welcome to the [Loco](https://loco.rs) Hello World Shuttle Template, designed with a focus on controllers and views (response schema). This minimalistic template comes with several features to kickstart your project: -## REST API Service without a Database +## Features +* REST API service without a database. * **Controllers:** Handle web requests parameters, body, validation, and render a response that is content-aware. We use Axum for the best performance, simplicity, and extensibility. Controllers also allow you to easily build middlewares, which can be used to add logic such as authentication, logging, or error handling before passing requests to the main controller actions. * **Views:** Loco can integrate with templating engines to generate dynamic HTML content from templates. * **Background Jobs:** Perform compute or I/O intensive jobs in the background with a Redis backed queue, or with threads. Implementing a worker is as simple as implementing a perform function for the Worker trait. @@ -12,8 +15,26 @@ Welcome to the [Loco](https://loco.rs) Hello World Shuttle Template, designed wi * **Storage:** In Loco Storage, we facilitate working with files through multiple operations. Storage can be in-memory, on disk, or use cloud services such as AWS S3, GCP, and Azure. * **Cache:** Loco provides an cache layer to improve application performance by storing frequently accessed data. -So see more Loco features, check out our [documentation website](https://loco.rs/docs/getting-started/tour/). +![Main page for Next.js + Shuttle Saas Template](./Mainpage.png) + +## Pre-requisites + +- Rust +- `loco` cli (for further development) +- [cargo-shuttle](https://www.shuttle.dev) ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `npm run deploy` which will build the static assets then deploy the service. + +## Troubleshooting + +- If you change the migrations after running locally or deploying, you will need to go into the database itself and + delete the tables. You can do this easily with something + like [psql](https://www.postgresql.org/docs/current/app-psql.html) or [pgAdmin](https://www.pgadmin.org/). +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/other/feature-flags/README.md b/other/feature-flags/README.md index 0293f1a0..fb62ff5b 100644 --- a/other/feature-flags/README.md +++ b/other/feature-flags/README.md @@ -1,7 +1,27 @@ # Cargo Feature Flags with Shuttle +## Introduction + An example that showcases how to use feature flags with Shuttle (see `Cargo.toml`). +## Features + +- Feature flags for conditionally enabling or disabling Shuttle (see `Cargo.toml`). + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `npm run deploy` which will build the static assets then deploy the service. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/other/standalone-binary/Cargo.toml b/other/standalone-binary/Cargo.toml index 3257ad10..46ea69ef 100644 --- a/other/standalone-binary/Cargo.toml +++ b/other/standalone-binary/Cargo.toml @@ -6,7 +6,7 @@ publish = false [[bin]] name = "multi-binary" -path = "src/bin/shuttle.rs" +path = "src/bin/shuttle.dev" [[bin]] name = "standalone" diff --git a/other/standalone-binary/README.md b/other/standalone-binary/README.md index cea07d14..382b7e07 100644 --- a/other/standalone-binary/README.md +++ b/other/standalone-binary/README.md @@ -1,16 +1,37 @@ # Standalone binary - run an app with Shuttle or standalone +## Introduction + This example shows how to separate a project's Shuttle logic from its core functionality so that two binaries can be made: one for running with `shuttle run` and deploying to Shuttle, and one that can be run with `cargo run --bin ...`. All startup logic is placed in the binary source files, while the implementation (endpoints etc) is moved to the library of the crate. -- `src/bin/shuttle.rs` is the main binary with Shuttle, run with `shuttle run`. Note that the `[[bin]]` entry in `Cargo.toml` needs to have the same name as the crate. The file can have any name you want. +- `src/bin/shuttle.dev` is the main binary with Shuttle, run with `shuttle run`. Note that the `[[bin]]` entry in `Cargo.toml` needs to have the same name as the crate. The file can have any name you want. - `src/bin/standalone.rs` is without Shuttle, run with `cargo run --bin standalone` (you can change the name) This example shows how to use separate logic for getting secrets (Shuttle secrets vs homemade solution), but the same approach can be applied to other resources that are initiated by Shuttle's main function. +## Features + +- Separate binaries to allow non-Shuttle deployments. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. You can use `cargo run --bin standalone` to run the non-Shuttle binary. + +When you're ready to deploy, use `npm run deploy` which will build the static assets then deploy the service. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're getting errors about not being able to find the right binary, make sure the binary name is the same as your project. diff --git a/poem/hello-world/README.md b/poem/hello-world/README.md index a7bd5bfc..23f66990 100644 --- a/poem/hello-world/README.md +++ b/poem/hello-world/README.md @@ -1,7 +1,27 @@ # Poem Hello World +## Introduction + An example that showcases using the `poem` web service framework with shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/poise/hello-world/README.md b/poise/hello-world/README.md index fb7cebbe..74c7c52a 100644 --- a/poise/hello-world/README.md +++ b/poise/hello-world/README.md @@ -1,7 +1,19 @@ # Poise Hello World Bot with Shuttle +## Introduction + In this example we will deploy a Poise/Serenity bot with Shuttle that responds to the `/hello` command with `world!`. To run this bot we need a valid Discord Token. To get started log in to the [Discord developer portal](https://discord.com/developers/applications). +## Features + +- A Discord bot that returns `world!` to the `/hello` command on a Discord server that you own (assuming the bot is on the server). + +## Pre-requisites + +- Rust +- Discord account +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template 1. Click the New Application button, name your application and click Create. @@ -15,4 +27,14 @@ To add the bot to a server we need to create an invite link. 2. Go to the URL Generator via the lefthand panel, and select the `bot` scope as well as the `Send Messages` permission in the Bot Permissions section. 3. Copy the URL, open it in your browser and select a Discord server you wish to invite the bot to. -For more information please refer to the [Discord docs](https://discord.com/developers/docs/getting-started) as well as the [Poise docs](https://docs.rs/poise) for more examples. +Run the project with `shuttle run`. + +When you're ready to deploy, use `shuttle deploy`. + +For more information on deploying Discord bots, please refer to the [Discord docs](https://discord.com/developers/docs/getting-started) as well as the [Poise docs](https://docs.rs/poise) for more examples. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're having trouble getting your bot to work, try checking your Discord token or your bot's intents via the Discord dev portal. diff --git a/rocket/dyn-templates/README.md b/rocket/dyn-templates/README.md index 712339f3..4f23e21c 100644 --- a/rocket/dyn-templates/README.md +++ b/rocket/dyn-templates/README.md @@ -1,9 +1,28 @@ # Rocket with dynamic templates using Handlebars +## Introduction + This example shows how to render templated content using Handlebars templates from [rocket](https://github.com/SergioBenitez/Rocket/) and shuttle. This example is inspired by templating example from the rocket repo, to see more ways to do this checkout the [original](https://github.com/SergioBenitez/Rocket/tree/master/examples/templating). -## How to use +## Features + +- Plain HTML-based frontend with HTML templating + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run the project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. -Run the project and visit . +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/rocket/hello-world/README.md b/rocket/hello-world/README.md index 9c5f1d49..9be0b559 100644 --- a/rocket/hello-world/README.md +++ b/rocket/hello-world/README.md @@ -1,7 +1,26 @@ # Rocket Hello World +## Introduction + An example that showcases using the `rocket` web service framework with Shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/rocket/jwt-authentication/README.md b/rocket/jwt-authentication/README.md index 775a8e0d..a847f31b 100644 --- a/rocket/jwt-authentication/README.md +++ b/rocket/jwt-authentication/README.md @@ -1,5 +1,7 @@ # Rocket with JWT authentication +## Introduction + This example shows how to use [Rocket request guards](https://rocket.rs/v0.5-rc/guide/requests/#request-guards) for authentication with [JSON Web Tokens](https://jwt.io/) (JWT for short). The idea is that all requests authenticate first at to get a JWT. Then the JWT is sent with all requests requiring authentication using the HTTP header `Authorization: Bearer `. @@ -7,59 +9,50 @@ Then the JWT is sent with all requests requiring authentication using the HTTP h This example uses the [`jsonwebtoken`](https://github.com/Keats/jsonwebtoken) which supports symmetric and asymmetric secret encoding, built-in validations, and most JWT algorithms. However, this example only makes use of symmetric encoding and validation on the expiration claim. -## Structure - -This example has two files to register routes and handle JWT claims. - -### src/main.rs - -Three Rocker routes are registered in this file: +## Features -1. `/public`: a route that can be called without needing any authentication. -2. `/login`: a route for posting a JSON object with a username and password to get a JWT. -3. `/private`: a route that can only be accessed with a valid JWT. +- A route that can be called without needing any authentication. +- A route for posting a JSON object with a username and password to get a JWT. +- A route that can only be accessed with a valid JWT. -### src/claims.rs +## Pre-requisites -The bulk of this example is in this file. Most of the code can be transferred to other frameworks except for the `FromRequest` implementation, which is Rocket specific. -This file contains a `Claims` object which can be expanded with more claims. A `Claims` can be created from a `Bearer ` string using `Claims::from_authorization()`. -And a `Claims` object can also be converted to a token using `to_token()`. - -## Deploy - -After logging into shuttle, use the following command to deploy this example: - -```sh -shuttle deploy -``` - -Now make a note of the `Host` for the deploy to use in the examples below. Or just use `authentication-rocket-app.shuttleapp.rs` as the host below. +- Rust +- [cargo-shuttle](https://www.shuttle.dev) ## How to use this template +Run the project with `shuttle run`. + First, we should be able to access the public endpoint without any authentication using: ```sh -curl https:///public +curl http://localhost:8000/public ``` But trying to access the private endpoint will fail with a 403 forbidden: ```sh -curl https:///private +curl https://localhost:8000/private ``` So let's get a JWT from the login route first: ```sh -curl --request POST --data '{"username": "username", "password": "password"}' https:///login +curl --request POST --data '{"username": "username", "password": "password"}' https://localhost:8000/login ``` Accessing the private endpoint with the token will now succeed: ```sh -curl --header "Authorization: Bearer " https:///private +curl --header "Authorization: Bearer " https://localhost:8000/private ``` The token is set to expire in 5 minutus, so wait a while and try to access the private endpoint again. Once the token has expired, a user will need to get a new token from login. Since tokens usually have a longer than 5 minutes expiration time, we can create a `/refresh` endpoint that takes an active token and returns a new token with a refreshed expiration time. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/rocket/opendal-memory/README.md b/rocket/opendal-memory/README.md index 0d9605ec..64d36c45 100644 --- a/rocket/opendal-memory/README.md +++ b/rocket/opendal-memory/README.md @@ -1,19 +1,36 @@ # OpenDAL Memory Storage -This example shows that how to connect to an in-memory storage using OpenDAL. +## Introduction -## Project structure +This example shows that how to connect to an in-memory storage using OpenDAL. The project consists of the following files - `Shuttle.toml` contains the name of the app - `src/main.rs` is where all the magic happens - it creates a Shuttle service with two endpoints: one for adding new data and one for retrieving it back. +## Features + +- Public routes for adding/retrieving data + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project, then try out the following `curl` command: +Run the project with `shuttle run`. +Then try the following `curl` command: +T ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todo --data '{"note":"My todo"}' # {"id":1,"note":"My todo"} ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/rocket/postgres/README.md b/rocket/postgres/README.md index 1d9f0a85..d823425a 100644 --- a/rocket/postgres/README.md +++ b/rocket/postgres/README.md @@ -1,10 +1,25 @@ # Rocket with Shuttle Shared DB (Postgres) +## Introduction + This template shows how to connect a Postgres database and use it for a simple TODO list app. +## Features + +- A database +- Two routes for retrieving/fetching data + +## Pre-requisites + +- Rust +- Docker if running locally +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project then try the following `curl` commands: +Run the project with `shuttle run`. + +Then try the following `curl` commands: ```bash curl -X POST -H 'content-type: application/json' localhost:8000/todo --data '{"note":"My todo"}' @@ -13,3 +28,10 @@ curl -X POST -H 'content-type: application/json' localhost:8000/todo --data '{"n curl localhost:8000/todos/1 # {"id":1,"note":"My todo"} ``` + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're running this locally, don't forget to have Docker installed and running! diff --git a/rocket/secrets/README.md b/rocket/secrets/README.md index 5db77390..354df518 100644 --- a/rocket/secrets/README.md +++ b/rocket/secrets/README.md @@ -1,12 +1,31 @@ ## Using Shuttle Secrets with Rocket +## Introduction + This example shows how to use secrets using [rocket](https://github.com/rwf2/rocket) and Shuttle. The secrets resource requires a `Secrets.toml` file to be present in your crate. Each like in this file should be a key-value pair that you can access using `SecretStore::get(&self, key)`. -## How to use +## Features + +- A route that displays the secret from `Secrets.toml` + +## Pre-requisites + +- Rust +- Docker if running locally +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Rename `Secrets.toml.example` to `Secrets.toml`, then run this project with `shuttle run`. + +Visit to try it out. -Rename `Secrets.toml.example` to `Secrets.toml` to use this example. +Once you're ready to deploy, use `shuttle deploy`. -Once done, run the example and visit . +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're getting errors, check your `Secrets.toml` file. diff --git a/rocket/static-files/README.md b/rocket/static-files/README.md index 78fcc0a1..b8e9264b 100644 --- a/rocket/static-files/README.md +++ b/rocket/static-files/README.md @@ -1,7 +1,26 @@ ## Serving Static Assets with Rocket +## Introduction + This example shows how to serve static assets using [rocket](https://github.com/rwf2/rocket) and Shuttle. -## Example usage +## Features + +- Plain HTML-based frontend + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run this project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. -Run the project and visit . +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/rocket/url-shortener/README.md b/rocket/url-shortener/README.md index 209e3f14..eb9fb85b 100644 --- a/rocket/url-shortener/README.md +++ b/rocket/url-shortener/README.md @@ -1,10 +1,23 @@ # Rocket URL Shortener -A URL shortener that you can use from your terminal - built with shuttle, rocket and postgres/sqlx. +## Introduction + +A URL shortener that you can use from your terminal - built with Shuttle, rocket and postgres/sqlx. + +## Features + +- Create shortened URLs from links! + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) ## How to use this template -You can use this URL shortener directly from your terminal. Just copy and paste this command to your terminal and replace `` with the URL that you want to shorten +Run this project with `shuttle run`. + +Once running, you can use this URL shortener directly from your terminal. Just copy and paste this command to your terminal and replace `` with the URL that you want to shorten ```bash curl -X POST -d '' https://s.shuttleapp.rs @@ -18,9 +31,9 @@ curl -X POST -d 'https://docs.rs/shuttle-service/latest/shuttle_service/' https: you will get the shortened URL back (something like this `https://s.shuttleapp.rs/RvpVU_`) -## Project structure - -The project consists of the following files +Once you're ready to deploy, use `shuttle deploy`. -- `migrations` folder is for DB migration files created by [sqlx-cli](https://github.com/launchbadge/sqlx/tree/master/sqlx-cli) -- `src/main.rs` is where all the magic happens - it creates a shuttle service with two endpoints: one for creating new short URLs and one for handling shortened URLs. +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If running locally, don't forget to make sure Docker is installed and running! diff --git a/rocket/workspace/README.md b/rocket/workspace/README.md index ff03961a..2b838752 100644 --- a/rocket/workspace/README.md +++ b/rocket/workspace/README.md @@ -1,6 +1,28 @@ # Rocket with Cargo Workspaces + +## Introduction + This example shows how to use a Cargo workspace with Shuttle using the `rocket` web service frameowrk. +## Features + +- A route that returns `Hello, world!`. +- Cargo workspace + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- The Shuttle package needs to be the default diff --git a/salvo/hello-world/README.md b/salvo/hello-world/README.md index fe8efdff..6ac4eee0 100644 --- a/salvo/hello-world/README.md +++ b/salvo/hello-world/README.md @@ -1,7 +1,27 @@ # Salvo Hello World +## Introduction + An example that showcases using the `salvo` web service framework with Shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/salvo/image-rescaler/README.md b/salvo/image-rescaler/README.md index b1fae7f8..2183b962 100644 --- a/salvo/image-rescaler/README.md +++ b/salvo/image-rescaler/README.md @@ -1,7 +1,27 @@ # Salvo image rescaler +## Introduction + This is a simple example showing how to use path parameters in Salvo and the `image` crate to load and manipulate an image. +## Features + +- A route that returns a resized version of the Shuttle logo. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Running the project and going to `/400/400` returns the Shuttle logo image but rescaled to 400 x 400 pixels. +Run the project with `shuttle run`. + +Visiting returns the Shuttle logo image but rescaled to 400 x 400 pixels. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/serenity/hello-world/README.md b/serenity/hello-world/README.md index ee219b3f..aa346b91 100644 --- a/serenity/hello-world/README.md +++ b/serenity/hello-world/README.md @@ -1,7 +1,19 @@ # Serenity Hello World Bot with Shuttle +## Introduction + In this example we will deploy a Serenity bot with Shuttle that responds to the `!hello` command with `world!`. To run this bot we need a valid Discord Token. To get started log in to the [Discord developer portal](https://discord.com/developers/applications). +## Features + +- A Discord bot that responds to `!hello` with `world!`. + +## Pre-requisites + +- Rust +- Discord account +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template 1. Click the New Application button, name your application and click Create. @@ -16,3 +28,15 @@ To add the bot to a server we need to create an invite link. 3. Copy the URL, open it in your browser and select a Discord server you wish to invite the bot to. For more information please refer to the [Discord docs](https://discord.com/developers/docs/getting-started) as well as the [Serenity repo](https://github.com/serenity-rs/serenity) for more examples. + +Run the project with `shuttle run`. + +Writing `!hello` into a channel your bot has access to will make it respond with `world!`. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're having trouble getting your bot to work, try checking your Discord token or your bot's intents via the Discord dev portal. diff --git a/serenity/postgres/README.md b/serenity/postgres/README.md index 7e912b85..19490c35 100644 --- a/serenity/postgres/README.md +++ b/serenity/postgres/README.md @@ -2,18 +2,28 @@ In this example we will deploy a Serenity bot with Shuttle that can add, list and complete todos using [Application Commands](https://discord.com/developers/docs/interactions/application-commands). To persist the todos we need a database. We will have Shuttle provison a PostgreSQL database for us by enabling the `sqlx-postgres` feature for `shuttle-service` and passing `#[shared::Postgres] pool: PgPool` as an argument to our `main` function. -## How to use this template +## Features + +- A Discord bot that adds application commands for adding, completing and listing to-dos. + +## Pre-requisites -To run this bot we need a valid Discord Token. To get started log in to the [Discord developer portal](https://discord.com/developers/applications). +- Rust +- Discord account +- Docker if running locally +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template 1. Click the New Application button, name your application and click Create. 2. Navigate to the Bot tab in the lefthand menu, and add a new bot. 3. On the bot page click the Reset Token button to reveal your token. Put this token in your `Secrets.toml`. It's very important that you don't reveal your token to anyone, as it can be abused. Create a `.gitignore` file to omit your `Secrets.toml` from version control. +4. For the sake of this example, you also need to scroll down on the bot page to the Message Content Intent section and enable that option. To add the bot to a server we need to create an invite link. 1. On your bot's application page, open the OAuth2 page via the lefthand panel. -2. Go to the URL Generator via the lefthand panel, and select the `applications.commands` scope. +2. Go to the URL Generator via the lefthand panel, and select the `bot` scope as well as the `Send Messages` permission in the Bot Permissions section. 3. Copy the URL, open it in your browser and select a Discord server you wish to invite the bot to. For this example we also need a `GuildId`. @@ -23,3 +33,16 @@ For this example we also need a `GuildId`. 3. Store it in `Secrets.toml` and retrieve it like we did for the Discord Token. For more information please refer to the [Discord docs](https://discord.com/developers/docs/getting-started) as well as the [Serenity repo](https://github.com/serenity-rs/serenity) for more examples. + +Run the project with `shuttle run`. + +Go back to your Discord server where your bot was invited to and try out some of the application commands. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're running locally don't ofrget to have Docker running! +- If you're having trouble getting your bot to work, try checking your Discord token or your bot's intents via the Discord dev portal. diff --git a/serenity/weather-forecast/README.md b/serenity/weather-forecast/README.md index d25e61f3..214f2cdf 100644 --- a/serenity/weather-forecast/README.md +++ b/serenity/weather-forecast/README.md @@ -2,6 +2,26 @@ A Discord bot created with Serenity that can get the weather forecast. +## Features + +- A Discord bot that can report the weather forecast. + +## Pre-requisites + +- Rust +- Discord account +- [accuweather.com](accuweather.com) API key +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -For a full tutorial on how to build and set up this bot, please refer to [Shuttle docs](https://docs.shuttle.rs/templates/tutorials/discord-weather-forecast) +For a full tutorial on how to build and set up this bot, please refer to [Shuttle docs](https://docs.shuttle.dev/templates/tutorials/discord-weather-forecast) + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're having trouble connecting to Discord, don't forget to check your `Secrets.toml` file and your bot's intents. +- If you're having trouble connecting to Accuweather, don't forget to check your `Secrets.toml` file. diff --git a/shuttle-cron/README.md b/shuttle-cron/README.md index 8b64b737..7c330312 100644 --- a/shuttle-cron/README.md +++ b/shuttle-cron/README.md @@ -1,5 +1,7 @@ # `shuttle-cron` +## Introduction + A service that prints out a log message at specified cron-style intervals. This example uses the `apalis` framework to be able to carry out cronjobs. A struct is defined that has some given data in it, and is stored in the Apalis monitor. We also implement a struct that holds a `chrono::DateTime`, which `apalis` uses internally for cron job streaming. @@ -8,6 +10,16 @@ When the cron job is called, the data is grabbed from the `JobContext` and we th The actual function to be ran itself is stored in `job_fn()` in the main function, as a function pointer. +## Features + +- A web service that can carry out cron-style scheduled tasks + +## Pre-requisites + +- Rust +- Docker if running locally +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template Run `shuttle run` to spin up the service locally. @@ -15,3 +27,11 @@ Run `shuttle run` to spin up the service locally. You can change the behavior of the cronjob by editing the `execute()` function for `CronjobData`. Note that the run method doesn't have to be an implementation method for `CronjobData` - you can write your own! + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. +- If you're running locally, don't forget to have Docker installed and running! diff --git a/thruster/hello-world/README.md b/thruster/hello-world/README.md index c9b7b5f2..cc34268f 100644 --- a/thruster/hello-world/README.md +++ b/thruster/hello-world/README.md @@ -1,7 +1,27 @@ # Thruster Hello World +## Introduction + An example that showcases using the `thruster` web service framework with Shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/tide/hello-world/README.md b/tide/hello-world/README.md index 9f157f1c..c71b5096 100644 --- a/tide/hello-world/README.md +++ b/tide/hello-world/README.md @@ -1,7 +1,27 @@ # Tide Hello World +## Introduction + An example that showcases using the `tide` web service framework with Shuttle. +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/tower/hello-world/README.md b/tower/hello-world/README.md index 50e1b68d..03bd1ffb 100644 --- a/tower/hello-world/README.md +++ b/tower/hello-world/README.md @@ -1,7 +1,27 @@ # Tower Hello World +## Introduction + An example that showcases using the `tower` web service framework (with `hyper`) with Shuttle. -## Example usage +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting -Run the project and visit . +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/tracing/custom-tracing-subscriber/README.md b/tracing/custom-tracing-subscriber/README.md index 16bf1d0a..b6390608 100644 --- a/tracing/custom-tracing-subscriber/README.md +++ b/tracing/custom-tracing-subscriber/README.md @@ -1,12 +1,31 @@ # Custom Tracing Subscriber with Shuttle +## Introduction + An example that showcases using a custom `tracing-subscriber` with Shuttle. Notes: - `default-features` is disabled on `shuttle-runtime` crate to allow this to be possible +## Features + +- A Shuttle serivce with a custom tracing subscriber. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out - you should get a message in your logs upon receiving the HTTP request. You can also additionally adjust the custom tracing subscriber as you want. + +Once you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. diff --git a/warp/hello-world/README.md b/warp/hello-world/README.md index d4a9accf..e2092546 100644 --- a/warp/hello-world/README.md +++ b/warp/hello-world/README.md @@ -1,7 +1,27 @@ # Warp Hello World -An example that showcases using the `warp` web service framework (with `hyper`) with Shuttle. +## Introduction + +An example that showcases using the `warp` web service framework with Shuttle. + +## Features + +- A route that returns `Hello, world!`. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) ## How to use this template -Run the project and visit . +Run the project with `shuttle run`. + +Visit to try it out. + +When you're ready to deploy, use `shuttle deploy`. + +## Troubleshooting + +- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add + the `--port ` to the `shuttle run` command to change this. From 71bc067ca73a9c1858c9aa852a46d2c6bcaf99dc Mon Sep 17 00:00:00 2001 From: Joshua Mo Date: Mon, 28 Oct 2024 18:22:45 +0000 Subject: [PATCH 6/6] fix: ci --- other/standalone-binary/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/other/standalone-binary/Cargo.toml b/other/standalone-binary/Cargo.toml index 46ea69ef..3257ad10 100644 --- a/other/standalone-binary/Cargo.toml +++ b/other/standalone-binary/Cargo.toml @@ -6,7 +6,7 @@ publish = false [[bin]] name = "multi-binary" -path = "src/bin/shuttle.dev" +path = "src/bin/shuttle.rs" [[bin]] name = "standalone"