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/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..674f63ba 100644 --- a/actix-web/clerk/README.md +++ b/actix-web/clerk/README.md @@ -1,4 +1,6 @@ -# Using Clerk auth with a Rust Actix web backend +# Actix Web with Clerk auth + +## Introduction This template uses Actix-web and the clerk-rs crate for providing authentication from Clerk in the backend. @@ -6,9 +8,21 @@ 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 a54d8987..30104437 100644 --- a/actix-web/cookie-authentication/README.md +++ b/actix-web/cookie-authentication/README.md @@ -1,7 +1,29 @@ -# Cookie authentication with actix-session +# 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. -Running the project and visiting will show the currently logged in user. +## Features + +- (basic) User-based session management +- Private/public routing + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## 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 new file mode 100644 index 00000000..c466e765 --- /dev/null +++ b/actix-web/hello-world/README.md @@ -0,0 +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 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 65fa4d2d..c00d6792 100644 --- a/actix-web/postgres/README.md +++ b/actix-web/postgres/README.md @@ -1,8 +1,22 @@ -# Shuttle shared Postgres DB with Actix Web +# 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. -## Example usage +## 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 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"}' @@ -11,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 5f770281..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 19340c2c..41879783 100644 --- a/actix-web/websocket-actorless/README.md +++ b/actix-web/websocket-actorless/README.md @@ -1,7 +1,27 @@ -# Actix Web actorless websockets +# Actix Web Actorless Websockets + +## Introduction This template shows how to use actorless websockets to build an API monitoring service and a simple chat app. -## Example usage +## Features + +- A plain HTML-based frontend +- Websocket connection + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +Run the project with `shuttle run`. + +Then 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/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 new file mode 100644 index 00000000..57b26100 --- /dev/null +++ b/axum/hello-world/README.md @@ -0,0 +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 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 9d09c004..9fea020b 100644 --- a/axum/htmx-crud/README.md +++ b/axum/htmx-crud/README.md @@ -1,9 +1,30 @@ -# Axum + htmx +# 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. -## Usage +## 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 15ecfdac..799443ba 100644 --- a/axum/jwt-authentication/README.md +++ b/axum/jwt-authentication/README.md @@ -1,3 +1,26 @@ -# JWT authentication in Axum +# 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). + +## 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`. + +## 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 new file mode 100644 index 00000000..e05e1bf5 --- /dev/null +++ b/axum/metadata/README.md @@ -0,0 +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 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 a867d286..a6f19918 100644 --- a/axum/oauth2/README.md +++ b/axum/oauth2/README.md @@ -1,16 +1,36 @@ -# Google OAuth in Axum +# Axum with Google OAuth + +## Introduction This template is an example of how you can implement Google OAuth using the Axum web framework in Rust. -## Prerequisites +## 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 776fbbdb..b4d5474a 100644 --- a/axum/openai/README.md +++ b/axum/openai/README.md @@ -1,7 +1,33 @@ +# Axum with OpenAI + +## Introduction + A simple endpoint that sends a chat message to ChatGPT and returns the response. -Set your OpenAI API key in `Secrets.toml`, then try it on a local run with: +## 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`. + +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 cccd4458..f592d6ce 100644 --- a/axum/postgres/README.md +++ b/axum/postgres/README.md @@ -1,8 +1,25 @@ -# Shuttle shared Postgres DB with Axum +# 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. -## Example usage +## Features + +- Public routes for fetching/creating notes using a database. + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +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"}' @@ -11,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 cf84257c..8d099206 100644 --- a/axum/qdrant/README.md +++ b/axum/qdrant/README.md @@ -1,8 +1,31 @@ -# Connect to a Qdrant Cloud DB from Shuttle +# Axum with Qdrant on Shuttle + +## Introduction This example shows how to use `shuttle-qdrant` to connect to a Qdrant vector database from Shuttle. -## Prerequisites +## 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 a8659eee..3d2179bc 100644 --- a/axum/static-files/README.md +++ b/axum/static-files/README.md @@ -1,5 +1,28 @@ -# Serving Static Assets with Axum +# 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). + +## 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`. + +## 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 new file mode 100644 index 00000000..8fe173b6 --- /dev/null +++ b/axum/turso/README.md @@ -0,0 +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 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 new file mode 100644 index 00000000..b0917584 --- /dev/null +++ b/axum/websocket/README.md @@ -0,0 +1,25 @@ +# Axum with Websockets + +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 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 634df8b5..acbfeef4 100644 --- a/bevy/hello-world/README.md +++ b/bevy/hello-world/README.md @@ -1,6 +1,21 @@ +# Bevy on Shuttle (with Axum) + +## Introduction + Example of how you can compile Bevy to WASM and run it on Shuttle. -## Instructions +## 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: ```bash @@ -18,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 new file mode 100644 index 00000000..b6d9063c --- /dev/null +++ b/custom-resource/pdo/README.md @@ -0,0 +1,29 @@ +# Custom Shuttle Resource + +## 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 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 new file mode 100644 index 00000000..ba2be37e --- /dev/null +++ b/custom-service/none/README.md @@ -0,0 +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 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 be6310d5..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) - -## Instructions for Usage +- 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) -- Initialize the template with: +## How to use this template - ```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 43915f96..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,12 +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 with `shuttle run`. + +Visit to try it out. -## Quick Start +When you're ready to deploy, use `npm run deploy` which will build the static assets then deploy the service. -To launch your app, simply use the following command: +## Troubleshooting -```sh -shuttle run -``` +- 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 new file mode 100644 index 00000000..fb62ff5b --- /dev/null +++ b/other/feature-flags/README.md @@ -0,0 +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 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/README.md b/other/standalone-binary/README.md index bdf1749f..382b7e07 100644 --- a/other/standalone-binary/README.md +++ b/other/standalone-binary/README.md @@ -1,10 +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 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 new file mode 100644 index 00000000..23f66990 --- /dev/null +++ b/poem/hello-world/README.md @@ -0,0 +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 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 2b5f36d9..74c7c52a 100644 --- a/poise/hello-world/README.md +++ b/poise/hello-world/README.md @@ -1,7 +1,21 @@ # 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. 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. @@ -13,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 58b00112..4f23e21c 100644 --- a/rocket/dyn-templates/README.md +++ b/rocket/dyn-templates/README.md @@ -1,5 +1,28 @@ -# Rendering Handlebars dynamic templates with Rocket +# 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). + +## 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`. + +## 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 new file mode 100644 index 00000000..9be0b559 --- /dev/null +++ b/rocket/hello-world/README.md @@ -0,0 +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 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 9fa918fd..a847f31b 100644 --- a/rocket/jwt-authentication/README.md +++ b/rocket/jwt-authentication/README.md @@ -1,4 +1,6 @@ -# Issue and verify JWT for authentication +# 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. @@ -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 +## Features -Three Rocker routes are registered in this file: +- 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. -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. +## Pre-requisites -### src/claims.rs +- Rust +- [cargo-shuttle](https://www.shuttle.dev) -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()`. +## How to use this template -## 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. - -### Seeing it in action +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 06a36220..64d36c45 100644 --- a/rocket/opendal-memory/README.md +++ b/rocket/opendal-memory/README.md @@ -1,10 +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 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 new file mode 100644 index 00000000..d823425a --- /dev/null +++ b/rocket/postgres/README.md @@ -0,0 +1,37 @@ +# 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 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"}' +# {"id":1,"note":"My todo"} + +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 988cbb6c..354df518 100644 --- a/rocket/secrets/README.md +++ b/rocket/secrets/README.md @@ -1,5 +1,31 @@ -## How to use +## 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)`. -Rename `Secrets.toml.example` to `Secrets.toml` to use this example. +## 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. + +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 getting errors, check your `Secrets.toml` file. diff --git a/rocket/static-files/README.md b/rocket/static-files/README.md new file mode 100644 index 00000000..b8e9264b --- /dev/null +++ b/rocket/static-files/README.md @@ -0,0 +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. + +## 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`. + +## 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 708beff5..eb9fb85b 100644 --- a/rocket/url-shortener/README.md +++ b/rocket/url-shortener/README.md @@ -1,10 +1,23 @@ -# Url Shortener +# Rocket URL Shortener -A URL shortener that you can use from your terminal - built with shuttle, rocket and postgres/sqlx. +## Introduction -## How to use it +A URL shortener that you can use from your terminal - built with Shuttle, rocket and postgres/sqlx. -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 +## Features + +- Create shortened URLs from links! + +## Pre-requisites + +- Rust +- [cargo-shuttle](https://www.shuttle.dev) + +## How to use this template + +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 new file mode 100644 index 00000000..2b838752 --- /dev/null +++ b/rocket/workspace/README.md @@ -0,0 +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 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 new file mode 100644 index 00000000..6ac4eee0 --- /dev/null +++ b/salvo/hello-world/README.md @@ -0,0 +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 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 25270691..2183b962 100644 --- a/salvo/image-rescaler/README.md +++ b/salvo/image-rescaler/README.md @@ -1,5 +1,27 @@ -# Image rescaler +# 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. -Running the project and going to `/400/400` returns the Shuttle logo image but rescaled to 400 x 400 pixels. +## 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 + +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 086084e4..aa346b91 100644 --- a/serenity/hello-world/README.md +++ b/serenity/hello-world/README.md @@ -1,7 +1,21 @@ # 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. 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. @@ -14,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 271d3ee8..19490c35 100644 --- a/serenity/postgres/README.md +++ b/serenity/postgres/README.md @@ -2,16 +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. -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 adds application commands for adding, completing and listing to-dos. + +## Pre-requisites + +- 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`. @@ -21,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 34b9de58..214f2cdf 100644 --- a/serenity/weather-forecast/README.md +++ b/serenity/weather-forecast/README.md @@ -1,3 +1,27 @@ # Serenity Weather Forecast Bot with Shuttle -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) +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.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 new file mode 100644 index 00000000..7c330312 --- /dev/null +++ b/shuttle-cron/README.md @@ -0,0 +1,37 @@ +# `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. + +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. + +## 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. + +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 new file mode 100644 index 00000000..cc34268f --- /dev/null +++ b/thruster/hello-world/README.md @@ -0,0 +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 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 new file mode 100644 index 00000000..c71b5096 --- /dev/null +++ b/tide/hello-world/README.md @@ -0,0 +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 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 new file mode 100644 index 00000000..03bd1ffb --- /dev/null +++ b/tower/hello-world/README.md @@ -0,0 +1,27 @@ +# Tower Hello World + +## Introduction + +An example that showcases using the `tower` web service framework (with `hyper`) 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 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/tracing/custom-tracing-subscriber/README.md b/tracing/custom-tracing-subscriber/README.md new file mode 100644 index 00000000..b6390608 --- /dev/null +++ b/tracing/custom-tracing-subscriber/README.md @@ -0,0 +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 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 new file mode 100644 index 00000000..e2092546 --- /dev/null +++ b/warp/hello-world/README.md @@ -0,0 +1,27 @@ +# Warp Hello World + +## 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 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.