Expand app quick start guides

site/content/integrate/apps/_index.md

@@ -5,23 +5,24 @@ description: "Apps are lightweight interactive add-ons to Mattermost."
 weight: 30
 ---
 
-Apps are lightweight, interactive add-ons to Mattermost which can be hosted as HTTP services, or as serverless functions on AWS Lambda, OpenFaaS, Kubernetes, etc. to run without dedicated infrastructure. Apps can:
+Apps are lightweight, interactive add-ons to Mattermost. They are hosted as their own service, as opposed to plugins which run directly alongside the server process.
+
+Apps can:
 
 - Display interactive, dynamic modal forms and message actions.
 - Be written in any language.
-- Attach themselves to locations in the Mattermost user interface (e.g. channel bar buttons, post menu, channel menu, commands), and can add their custom slash commands with full autocomplete.
+- Attach themselves to locations in the Mattermost user interface (e.g. channel bar buttons, post menu, channel menu, commands), and add their custom slash commands with full autocomplete.
 - Receive webhooks from Mattermost, and third-parties, and use the Mattermost REST APIs to post messages, etc.
-- Work on both Mobile and Desktop clients so developers can focus on the functionality of their apps.
-- Be deployed using our serverless hosting infrastructure keeping data secure and supporting scalability by being stateless.
+- Work on both Mobile and Desktop clients. This way, developers can focus on the features of their Apps without writing code for each specific platform.
 - Include dynamic fields, code as an on-demand function, and interactive modals.
 
-When you develop using the Apps Framework, your apps can:
+When you develop using the Apps framework, your Apps can:
 
 - Create slash commands
 
   ![image](app-slash-command-zoomed-in.png)
 
-- Post messages to channels
+- Post messages to channels (and anything else possible with [Mattermost's API](https://api.mattermost.com/))
 
   ![image](app-bot.png)
 
@@ -33,53 +34,53 @@ When you develop using the Apps Framework, your apps can:
 
 Apps are now generally available and we always appreciate your feedback! Share constructive feedback in the [Mattermost Apps channel](https://community.mattermost.com/core/channels/mattermost-apps) on our Mattermost community instance.
 
-Read the [JavaScript start guide]({{< ref "quickstart/quick-start-js" >}}) or [Go quick start guide]({{< ref "quickstart/quick-start-go" >}}) to learn how to write your first App.
+We have quick start guides for [TypeScript]({{< ref "quickstart/quick-start-ts" >}}), [Go]({{< ref "quickstart/quick-start-go" >}}), and [Python]({{< ref "quickstart/quick-start-python" >}}) to learn how to write your first App.
 
 ## FAQ
 
-### When would you build an app vs. a custom slash command vs. a webhook vs. a plugin?
+### When would you build an App vs. a custom slash command vs. a webhook vs. a plugin?
 
 That depends on your use case, as they each have benefits.
 
-The built-in [incoming webhook]({{< ref "/integrate/webhooks/incoming" >}}) is great for simple use cases. It requires the incoming payload to contain a valid {{< newtabref href="https://pkg.go.dev/github.com/nhannv/mattermost-server/model#Post" title="Post" >}} JSON object, but some external systems don't allow customization of the fields included in the webhook payload. Compared to built-in webhooks, an App or plugin can be customized to receive an HTTP webhook posting from another system, and can process the incoming data then augment it or make an actionable message in a channel.
+Each type of existing integration type is sort of a la carte, whereas the App framework is an all-in-one package that supports its own version of some of those out of the box. Meaning when you install an App, you don't need to go create a separate bot account, OAuth app, webhooks etc. Some pieces are reused, such as the bot account mechanism, but some pieces were remade and are not reused, such as webhooks.
+
+In the case of webhooks, the existing mechanism is only able to create posts, and only accepts an [incoming webhook]({{< ref "/integrate/webhooks/incoming" >}}) payload. It does not support other logic for handling arbitrary data structures from external systems.
 
-A plugin should be used when you need to [directly alter the UI]({{< ref "integrate/plugins/components/webapp/best-practices" >}}) in Mattermost or you have a feature that requires low latency with the server (such as replacing characters in any message [before it is saved]({{< ref "integrate/plugins/components/server/reference#Hooks.MessageWillBePosted" >}})). Currently, plugins have several [UX hooks]({{< ref "integrate/plugins/components/server/reference#Hooks" >}}) that apps cannot access, however we plan to add/migrate more UX hooks into the Apps Framework over time. Please see the [plugin documentation]({{< ref "integrate/plugins" >}}) for more information.
+A plugin should be used when you need to [directly alter the UI]({{< ref "integrate/plugins/components/webapp/best-practices" >}}) in Mattermost or you have a feature that requires low latency with the server (such as replacing characters in any message [before it is saved]({{< ref "integrate/plugins/components/server/reference#Hooks.MessageWillBePosted" >}})). It should be noted that plugins have several [UX hooks]({{< ref "integrate/plugins/components/server/reference#Hooks" >}}) that Apps cannot access. Please see the [plugin documentation]({{< ref "integrate/plugins" >}}) for more information.
 
 ### What's the difference between the Apps framework and the plugin framework?
 
-The Apps Framework provides a few differences from plugins, including:
+The Apps framework provides a few differences from plugins, including:
 
-- Interactive elements are easier to use and develop.
-- Compatible with both Mobile and Desktop clients without any extra code.
+-   Interactive elements are easier to use and develop.
+-   Compatible with both Mobile and Desktop clients without any extra code.
 
-### What language should I use to write apps?
+### What language should I use to write Apps?
 
-Any language you want. We currently have an [official driver for Go](https://pkg.go.dev/github.com/mattermost/mattermost-plugin-apps/apps), and we are planning to release other drivers in the future in conjunction with our community.
+Any language you want. We currently have an [official driver for Go](https://pkg.go.dev/github.com/mattermost/mattermost-plugin-apps/apps).
 
-### How and where will my app be hosted?
+### How and where will my App be hosted?
 
-1. **[Mattermost Cloud](https://mattermost.com/mattermost-cloud/)** apps. Cloud
-   customers can use apps from Mattermost Marketplace. Marketplace apps are
+1. **[Mattermost Cloud](https://mattermost.com/mattermost-cloud/)** Apps. Cloud
+   customers can use Apps from Mattermost Marketplace. Marketplace Apps are
    deployed as AWS Lambda functions, and their usage is included in the service.
-   You can find more information about the Marketplace [here](https://mattermost.com/marketplace/). Example AWS Lambda apps can be
+   You can find more information about the Marketplace [here](https://mattermost.com/marketplace/). Example AWS Lambda Apps can be
    found
-   [here](https://github.com/mattermost/mattermost-plugin-apps/tree/master/examples/js/aws_hello)
-   (JavaScript) and
-   [here](https://github.com/mattermost/mattermost-plugin-apps/tree/master/examples/go/hello-serverless)
-   (go).
-2. **External** (HTTP) apps. Apps can be hosted as publicly (or privately) available HTTP
+   [here](https://github.com/mattermost/mattermost-app-examples/tree/master/golang/serverless)
+   (Go).
+2. **External** (HTTP) Apps. Apps can be hosted as publicly (or privately) available HTTP
    services, the choice of hosting provider is yours. A self-managed Mattermost
-   customer would be able to install your app from a URL. External apps are not
+   customer would be able to install your App from a URL. External Apps are not
    currently accepted in the Mattermost Marketplace.
-3. **Customer-deployable** apps. An app can be packaged as a bundle, deployable
+3. **Customer-deployable** Apps. An App can be packaged as a bundle, deployable
    by the customer in their own hosting environment. Currently, [AWS
    Lambda](https://aws.amazon.com/lambda/),
    [OpenFaaS](https://www.openfaas.com/), and [Kubeless](https://kubeless.io/)
    are supported, with plans for more serverless platforms, Kubernetes, and
-   docker compose. Customer-deployable apps are not yet distributed via the
+   docker compose. Customer-deployable Apps are not yet distributed via the
    Mattermost Marketplace.
 
-### Can I write "internal" organization-specific apps?
+### Can I write "internal" organization-specific Apps?
 
 Yes. They can be packaged as "customer-deployable" bundles and then deployed on
 the supported serverless platforms, or run as HTTP services on the

site/content/integrate/apps/quickstart/_index.md

@@ -1,18 +1,65 @@
 ---
-title: Quick start
-description: Guides for quickly getting started building apps
+title: Apps - Developer setup
+description: Developer setup and guides for quickly getting started building Apps
 weight: 10
 ---
 
-The Apps quick start guides get you started developing your App in a variety of languages.
+To get started making Mattermost Apps, the first thing you need to do is set up your development environment via the [mattermost-app-examples repository](https://github.com/mattermost/mattermost-app-examples). Then you can follow language-specific guides to get started with the Apps framework, or just start tinkering on your own.
 
-| Language                | Guide                                                                                             |
-|-------------------------|---------------------------------------------------------------------------------------------------|
-| Golang                  | [Quick start guide (Go)]({{< ref "/integrate/apps/quickstart/quick-start-go" >}})                 |
-| Golang (Serverless)     | [Quick start guide (serverless)]({{< ref "/integrate/apps/quickstart/quick-start-serverless" >}}) |
-| JavaScript / TypeScript | [Quick start guide (NodeJS)]({{< ref "/integrate/apps/quickstart/quick-start-js" >}})             |
+## Prerequisites
 
-## Tests
+You need the latest version of [Docker Desktop](https://docs.docker.com/desktop/) (Windows, Mac, or Linux desktop application) or [Docker Engine](https://docs.docker.com/engine/) (CLI) installed.
 
-### Coming soon!
-In the future this section will describe how to set up an environment for testing Apps.
+## Set up your development environment
+
+Clone and enter a local copy of the [mattermost-app-examples repository](https://github.com/mattermost/mattermost-app-examples) with the following command:
+
+```sh
+git clone https://github.com/mattermost/mattermost-app-examples && cd mattermost-app-examples
+```
+
+When you're developing your own App, you need an actual Mattermost Server to be running. The development environment accomplishes this by using a [`docker-compose.yml`](https://github.com/mattermost/mattermost-app-examples/blob/master/docker-compose.yml) with a network named `mattermost-apps-dev`. This Docker Compose file has just two containers: the Mattermost Server and a Postgres database.
+
+The Mattermost image itself is preconfigured with settings for local App development but you can customize them. For example, the `MM_SERVICESETTINGS_SITEURL` environment variable is set to `http://mattermost:8065` on the Mattermost container, but you could change this to be any URL, like one from [ngrok](https://ngrok.com/) or [Gitpod](https://gitpod.io/).
+
+Because they exist on a pre-defined network, other `docker-compose.yml` configurations can connect their containers to this development environment by specifying the same `mattermost-apps-dev` Docker network. Then the Mattermost Server can be accessed at `http://mattermost:8065` by any other container on the `mattermost-apps-dev` network. Similarly, your own development Apps can then be accessed by Mattermost via their service name (e.g., `http://mattermost-apps-typescript-hello-world:4000`). You can learn more about Docker networks in the [official documentation](https://docs.docker.com/network/).
+
+You can also access Mattermost from outside the Docker network via [http://localhost:8065](http://localhost:8065). Similarly, the examples provided in the [mattermost-app-examples repository](https://github.com/mattermost/mattermost-app-examples) can be accessed at their designated ports on `localhost`. This is because the Docker Compose files have been configured to expose the appropriate ports locally.
+
+To change the Mattermost Apps plugin or the Mattermost Server versions, you can edit [`docker-compose.yml`](https://github.com/mattermost/mattermost-app-examples/blob/master/docker-compose.yml).
+
+Next, use the following command to bring your development environment online.
+
+```sh
+docker compose up -d
+```
+
+Once Mattermost is online, you can access the server at [http://localhost:8065](http://localhost:8065) and create your superuser account.
+
+To temporarily stop the container (and preserve your database), use the following command:
+
+```sh
+docker compose stop
+```
+
+To stop and clean up the database (for a fresh start), use the following command:
+
+```sh
+docker compose down
+```
+
+Now you're fully equipped with an environment to develop Mattermost Apps locally!
+
+## Quick start guides
+
+The following quick start guides can help you start developing a Mattermost App in different languages:
+
+| Language   | Guide                                                                                                  |
+| ---------- | ------------------------------------------------------------------------------------------------------ |
+| Go         | [Hello World in Go]({{< ref "/integrate/apps/quickstart/quick-start-go" >}})                           |
+| Go         | [JWT in Go]({{< ref "/integrate/apps/quickstart/quick-start-jwt" >}})                                  |
+| Go         | [Serverless on AWS or OpenFaaS in Go]({{< ref "/integrate/apps/quickstart/quick-start-serverless" >}}) |
+| TypeScript | [Hello World in TypeScript]({{< ref "/integrate/apps/quickstart/quick-start-ts" >}})                   |
+| Python     | [Hello World in Python]({{< ref "/integrate/apps/quickstart/quick-start-python" >}})                   |
+
+More guides from community members are encouraged! Check out the [open issue](https://github.com/mattermost/mattermost-plugin-apps/issues/351) and our [contributing guide]({{< ref "/contribute/getting-started" >}}) for more details.