docs: give every template a README.md

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

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`.
 

actix-web/clerk/README.md

@@ -1,14 +1,28 @@
-# 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.
 
 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 <https://clerk.com/docs/quickstarts/react>.
 
-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 <port-number>` to the `shuttle run` command to change this.

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 <http://localhost:8000> 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 <http://localhost:8000> will show the currently logged in user.
 Visiting <http://localhost:8000/login> will log you in as `user1` (no authentication logic is in place).
 Visiting <http://localhost:8000/logout> 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 <port-number>` to the `shuttle run` command to change this.

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 <http://localhost:8000> 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 <port-number>` to the `shuttle run` command to change this.

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 <port-number>` to the `shuttle run` command to change this.
+- If you're running locally, don't forget to have Docker installed and running!

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 <http://localhost:8000/index.html>):
 
 ```bash
 curl localhost:8000/index.html
 # <h1>Hello world!</h1>
 ```
+
+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 <port-number>` to the `shuttle run` command to change this.

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 <http://localhost:8000/index.html> to try it out!
+
+Once you're ready to deploy, use `shuttle deploy`.
 
-Run the app and go to <http://localhost:8000>.
+## Troubleshooting
+- Shuttle connects by default to port 8000 - if you're currently already using something at port 8000, you can add
+  the `--port <port-number>` to the `shuttle run` command to change this.

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<WsState>,

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 <http://localhost:8000> 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 <port-number>` to the `shuttle run` command to change this.

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 <http://localhost:8000> 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 <port-number>` to the `shuttle run` command to change this.

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 <http://localhost:8000> 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 <port-number>` to the `shuttle run` command to change this.

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 <http://localhost:8000> 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 <port-number>` to the `shuttle run` command to change this.

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 <port-number>` to the `shuttle run` command to change this.