Improve readmes (#171)

Author: marcuskohlberg

README.md

@@ -6,43 +6,71 @@ When a new appointment is booked, the backend sends a confirmation email to the
 
 It has a React frontend with both a user facing part and an admin dashboard. Authentication is required for accessing admin dashboard.
 
-## Developing locally
+## Prerequisites 
 
-When you have [installed Encore](https://encore.dev/docs/install), you can create a new Encore application and clone this example with this command.
+**Install Encore:**
+- **macOS:** `brew install encoredev/tap/encore`
+- **Linux:** `curl -L https://encore.dev/install.sh | bash`
+- **Windows:** `iwr https://encore.dev/install.ps1 | iex`
+  
+**Docker:**
+1. [Install Docker](https://docker.com)
+2. Start Docker
+
+## Create app
+
+Create a local app from this template:
 
 ```bash
 encore app create my-app-name --example=booking-system
 ```
 
-## Running locally
+## Run app locally
+
+Before running your application, make sure you have Docker installed and running. Then run this command from your application's root folder:
 
-Run your application:
 ```bash
 encore run
 ```
 
+## View the frontend
+
+While `encore run` is running, head over to [http://localhost:4000/frontend/](http://localhost:4000/frontend/) to view the frontend for your booking system monitor.
+
+
 ## Local Development Dashboard
 
 While `encore run` is running, open [http://localhost:9400/](http://localhost:9400/) to access Encore's [local developer dashboard](https://encore.dev/docs/observability/dev-dash).
 
-Here you can see API docs, make requests in the API explorer, and view traces of the responses.
+Here you can see traces for all the request that were generated when you used your app from the frontend, view your architecture diagram, and see API docs in the Service Catalog.
 
-## View the frontend
-
-While `encore run` is running, head over to [http://localhost:4000/frontend/](http://localhost:4000/frontend/) to view the frontend for your booking system monitor.
 
 ## Deployment
 
-Deploy your application to a staging environment in Encore's free development cloud:
+### Self-hosting
+
+See the [self-hosting instructions](https://encore.dev/docs/self-host/docker-build) for how to use `encore build docker` to create a Docker image and configure it.
+
+### Encore Cloud Platform
+
+Deploy your application to a free staging environment in Encore's development cloud using `git push encore`:
 
 ```bash
 git add -A .
 git commit -m 'Commit message'
 git push encore
 ```
 
-Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.
+You can also open your app in the [Cloud Dashboard](https://app.encore.dev) to integrate with GitHub, or connect your AWS/GCP account, enabling Encore to automatically handle cloud deployments for you.
+
+## Link to GitHub
+
+Follow these steps to link your app to GitHub:
 
-From there you can also connect your own AWS or GCP account to use for deployment.
+1. Create a GitHub repo, commit and push the app.
+2. Open your app in the [Cloud Dashboard](https://app.encore.dev).
+3. Go to **Settings ➔ GitHub** and click on **Link app to GitHub** to link your app to GitHub and select the repo you just created.
+4. To configure Encore to automatically trigger deploys when you push to a specific branch name, go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the **Branch name** and hit **Save**.
+5. Commit and push a change to GitHub to trigger a deploy.
 
-Now off you go into the clouds!
+[Learn more in the docs](https://encore.dev/docs/how-to/github)

booking-system/README.md

@@ -2,17 +2,28 @@
 
 This starter shows how you can build a GraphQL server with Encore, implementing a basic url shortener as an example.
 
-## Developing locally
+## Prerequisites 
 
-When you have [installed Encore](https://encore.dev/docs/install), you can create a new Encore application and clone this example with this command.
+**Install Encore:**
+- **macOS:** `brew install encoredev/tap/encore`
+- **Linux:** `curl -L https://encore.dev/install.sh | bash`
+- **Windows:** `iwr https://encore.dev/install.ps1 | iex`
+  
+**Docker:**
+1. Install [Docker](https://docker.com)
+2. Start Docker
+
+## Create app
+
+Create a local app from this template:
 
 ```bash
 encore app create my-app-name --example=graphql
 ```
 
-## Running locally
+## Run app locally
 
-Before running your application, make sure you have Docker installed and running. It's required to locally run Encore applications with databases.
+Before running your application, make sure you have Docker installed and running. Then run this command from your application's root folder:
 
 ```bash
 encore run
@@ -62,19 +73,33 @@ query {
 
 ## Deployment
 
-Deploy your application to a staging environment in Encore's free development cloud:
+### Self-hosting
+
+See the [self-hosting instructions](https://encore.dev/docs/self-host/docker-build) for how to use `encore build docker` to create a Docker image and configure it.
+
+### Encore Cloud Platform
+
+Deploy your application to a free staging environment in Encore's development cloud using `git push encore`:
 
 ```bash
 git add -A .
 git commit -m 'Commit message'
 git push encore
 ```
 
-Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.
+You can also open your app in the [Cloud Dashboard](https://app.encore.dev) to integrate with GitHub, or connect your AWS/GCP account, enabling Encore to automatically handle cloud deployments for you.
+
+## Link to GitHub
+
+Follow these steps to link your app to GitHub:
 
-From there you can also connect your own AWS or GCP account to use for deployment.
+1. Create a GitHub repo, commit and push the app.
+2. Open your app in the [Cloud Dashboard](https://app.encore.dev).
+3. Go to **Settings ➔ GitHub** and click on **Link app to GitHub** to link your app to GitHub and select the repo you just created.
+4. To configure Encore to automatically trigger deploys when you push to a specific branch name, go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the **Branch name** and hit **Save**.
+5. Commit and push a change to GitHub to trigger a deploy.
 
-Now off you go into the clouds!
+[Learn more in the docs](https://encore.dev/docs/how-to/github)
 
 ## Testing
 

graphql/README.md

@@ -2,15 +2,25 @@
 
 This is a RESTful API Starter with a single Hello World API endpoint.
 
-## Developing locally
+## Prerequisites 
 
-When you have [installed Encore](https://encore.dev/docs/install), you can create a new Encore application and clone this example with this command.
+**Install Encore:**
+- **macOS:** `brew install encoredev/tap/encore`
+- **Linux:** `curl -L https://encore.dev/install.sh | bash`
+- **Windows:** `iwr https://encore.dev/install.ps1 | iex`
+
+## Create app
+
+Create a local app from this template:
 
 ```bash
 encore app create my-app-name --example=hello-world
 ```
 
-## Running locally
+## Run app locally
+
+Run this command from your application's root folder:
+
 ```bash
 encore run
 ```
@@ -25,21 +35,37 @@ To see that your app is running, you can ping the API.
 curl http://localhost:4000/hello/World
 ```
 
+When you ping the API, you will see traces and logs appearing in the local development dashboard: <http://localhost:9400/>
+
 ## Deployment
 
-Deploy your application to a staging environment in Encore's free development cloud:
+### Self-hosting
+
+See the [self-hosting instructions](https://encore.dev/docs/self-host/docker-build) for how to use `encore build docker` to create a Docker image and configure it.
+
+### Encore Cloud Platform
+
+Deploy your application to a free staging environment in Encore's development cloud using `git push encore`:
 
 ```bash
 git add -A .
 git commit -m 'Commit message'
 git push encore
 ```
 
-Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.
+You can also open your app in the [Cloud Dashboard](https://app.encore.dev) to integrate with GitHub, or connect your AWS/GCP account, enabling Encore to automatically handle cloud deployments for you.
+
+## Link to GitHub
+
+Follow these steps to link your app to GitHub:
 
-From there you can also connect your own AWS or GCP account to use for deployment.
+1. Create a GitHub repo, commit and push the app.
+2. Open your app in the [Cloud Dashboard](https://app.encore.dev).
+3. Go to **Settings ➔ GitHub** and click on **Link app to GitHub** to link your app to GitHub and select the repo you just created.
+4. To configure Encore to automatically trigger deploys when you push to a specific branch name, go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the **Branch name** and hit **Save**.
+5. Commit and push a change to GitHub to trigger a deploy.
 
-Now off you go into the clouds!
+[Learn more in the docs](https://encore.dev/docs/how-to/github)
 
 ## Testing
 

hello-world/README.md

@@ -2,10 +2,20 @@
 
 This is an [Encore](https://encore.dev/) + [Next.js](https://nextjs.org/) project starter. It's a great way to learn how to combine Encore's backend capabilities with a modern web framework — perfect for building a web app.
 
-## Developing locally
+## Prerequisites 
 
-When you have [installed Encore](https://encore.dev/docs/install), you can create a new Encore application and clone
-this example by running this command:
+- **Install Encore:**
+  - **macOS:** `brew install encoredev/tap/encore`
+  - **Linux:** `curl -L https://encore.dev/install.sh | bash`
+  - **Windows:** `iwr https://encore.dev/install.ps1 | iex`
+  
+- **Docker:**
+  - 1. Install [Docker](https://docker.com)
+  - 2. Start Docker
+
+## Create app
+
+Create a local app from this template:
 
 ```bash
 encore app create my-app --example=nextjs-starter
@@ -45,20 +55,21 @@ npm run gen:local # Locally running Encore backend
 
 ## Deployment
 
-### Encore
+### Encore: Self-hosting
+
+See the [self-hosting instructions](https://encore.dev/docs/self-host/docker-build) for how to use `encore build docker` to create a Docker image and configure it.
 
-Deploy your backend to a staging environment in Encore's free development cloud:
+### Encore: Cloud Platform
+
+Deploy your application to a free staging environment in Encore's development cloud using `git push encore`:
 
 ```bash
 git add -A .
 git commit -m 'Commit message'
 git push encore
 ```
 
-Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.
-
-From there you can also see metrics, traces, connect your app to a
-GitHub repo to get automatic deploys on new commits, and connect your own AWS or GCP account to use for deployment.
+You can also open your app in the [Cloud Dashboard](https://app.encore.dev) to integrate with GitHub, or connect your AWS/GCP account, enabling Encore to automatically handle cloud deployments for you.
 
 ### Next.js on Vercel
 

nextjs-starter/README.md

@@ -6,41 +6,105 @@ This is an Encore starter application for a Slack bot. It brings the greatness o
 
 If you prefer to built it yourself, check out the [written tutorial](https://encore.dev/docs/tutorials/slack-bot) to learn how to build this application from scratch.
 
-## Developing locally
+## Prerequisites 
 
-When you have [installed Encore](https://encore.dev/docs/install), you can create a new Encore application and clone this example with this command.
+**Install Encore:**
+- **macOS:** `brew install encoredev/tap/encore`
+- **Linux:** `curl -L https://encore.dev/install.sh | bash`
+- **Windows:** `iwr https://encore.dev/install.ps1 | iex`
+  
+**Slack Workspace:**
+- You need to have a Slack Workspace where you are authorized to create Slack apps.
+
+## Create app
+
+Create a local app from this template:
 
 ```bash
 encore app create my-app-name --example=slack-bot
 ```
 
-## Running locally
+## Setup Slack integration
+
+The first step is to create a new Slack app:
+1. Head over to [Slack's API site](https://api.slack.com/apps) and create a new app.
+2. When prompted, choose to create the app **from an app manifest**.
+3. Choose a workspace to install the app in.
+
+Enter the following manifest (replace `$APP_ID` in the URL below with your Encore app id):
+
+```yaml
+_metadata:
+  major_version: 1
+display_information:
+  name: Encore Bot
+  description: Cowsay for the cloud age.
+features:
+  slash_commands:
+    - command: /cowsay
+      # Replace $APP_ID below
+      url: https://staging-$APP_ID.encr.app/cowsay
+      description: Say things with a flair!
+      usage_hint: your message here
+      should_escape: false
+  bot_user:
+    display_name: encore-bot
+    always_online: true
+oauth_config:
+  scopes:
+    bot:
+      - commands
+      - chat:write
+      - chat:write.public
+settings:
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+```
+
+Next, head over to the configuration section for your Slack app (go to [Your Apps](https://api.slack.com/apps) → select your app → Basic Information).
 
-Run your application:
+Copy the **Signing Secret** and then run the following command and paste the secret to store it using Encore's built-in secrets manager:
 ```bash
-encore run
+ encore secret set --type local,dev,pr,prod SlackSigningSecret
 ```
-To use the Slack integration, set the Slack signing secret (see tutorial above):
+
+## Run app locally
+
+Run this command from your application's root folder:
+
 ```bash
-encore secret set SlackSigningSecret
+encore run
 ```
 
-## Open the developer dashboard
-
-While `encore run` is running, open [http://localhost:9400/](http://localhost:9400/) to access Encore's [local developer dashboard](https://encore.dev/docs/observability/dev-dash).
+**Note:** This app doesn't do much when running locally, you need to deploy it (see below) for Slack to be able to communicate with the program and for the bot to work.
 
 ## Deployment
 
-Deploy your application to a staging environment in Encore's free development cloud:
+### Self-hosting
+
+See the [self-hosting instructions](https://encore.dev/docs/self-host/docker-build) for how to use `encore build docker` to create a Docker image and configure it.
+
+### Encore Cloud Platform
+
+Deploy your application to a free staging environment in Encore's development cloud using `git push encore`:
 
 ```bash
 git add -A .
 git commit -m 'Commit message'
 git push encore
 ```
 
-Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.
+You can also open your app in the [Cloud Dashboard](https://app.encore.dev) to integrate with GitHub, or connect your AWS/GCP account, enabling Encore to automatically handle cloud deployments for you.
+
+## Link to GitHub
+
+Follow these steps to link your app to GitHub:
 
-From there you can also connect your own AWS or GCP account to use for deployment.
+1. Create a GitHub repo, commit and push the app.
+2. Open your app in the [Cloud Dashboard](https://app.encore.dev).
+3. Go to **Settings ➔ GitHub** and click on **Link app to GitHub** to link your app to GitHub and select the repo you just created.
+4. To configure Encore to automatically trigger deploys when you push to a specific branch name, go to the **Overview** page for your intended environment. Click on **Settings** and then in the section **Branch Push** configure the **Branch name** and hit **Save**.
+5. Commit and push a change to GitHub to trigger a deploy.
 
-Now off you go into the clouds!
+[Learn more in the docs](https://encore.dev/docs/how-to/github)