add app deployment guides (#6720)

* add app deployment guides * add deploy app link to deployment index page * fix route not showing on side menu --------- Co-authored-by: Carrie Warner (Mattermost) <[email protected]>
mattermost · Oct 30, 2023 · 85348fd · 85348fd
1 parent 0a14da1
commit 85348fd
Show file tree

Hide file tree

Showing 9 changed files with 352 additions and 15 deletions.
diff --git a/source/guides/configure-app-framework.rst b/source/guides/configure-app-framework.rst
@@ -0,0 +1,10 @@
+Configure the Apps Framework
+============================
+
+The Apps framework includes a built-in slash command, ``/apps settings``, that allows for the configuration of system-wide settings.
+
+Configuration settings
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Enable Developers Mode**: Enable debugging feature for the Apps Plugin. Disabled by default.
+- **Enable HTTP apps**: Allow HTTP apps to be installed. Disabled by default on Cloud servers.
diff --git a/source/guides/deploy-aws.rst b/source/guides/deploy-aws.rst
@@ -0,0 +1,157 @@
+Deploy Apps to AWS
+==================
+
+Deployment in self-managed environments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An App designed and bundled for AWS Lambda can be deployed to the customer's own
+AWS environment, and then installed on a self-managed ("on-prem") Mattermost
+instance. Note that the only AWS-hosted apps available on Mattermost Cloud instances are the ones by Mattermost.
+
+For details on how to develop and package apps for AWS see `Package / AWS <package-aws.html>`_.
+
+There are three steps required to enable AWS applications on a self-managed Mattermost instance.
+
+1. Initialize the AWS environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set up AWS S3 bucket
+^^^^^^^^^^^^^^^^^^^^
+
+You will need to create an S3 bucket within AWS or use an existing bucket.
+
+1. Visit https://s3.console.aws.amazon.com
+2. Create a bucket.
+3. **Bucket name**: Give your bucket a name, later used in ``MM_APPS_S3_BUCKET`` environment variable.
+4. **AWS Region**:
+    a. Select your region
+    b. Save the slug value for later, to be used in ``MM_APPS_AWS_REGION`` environment variable (Example: ``us-east-1``)
+    - Corresponding Lambdas will be deployed in the same region
+5. **Block Public Access settings for this bucket**
+    a. (Optional) Check **Block *all* public access**
+6. Select **Create Bucket**.
+
+Create a privileged IAM user access key and secret
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You will need an access key and secret so that ``appsctl`` can deploy the app. These credentials can come from creating an IAM user, using a privileged IAM user, or even using the AWS account owners personal access key. Please follow the instructions provided by AWS (https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/) to complete these steps and save the ``Access key ID`` and ``Secret access key`` values.
+
+Set AWS_DEPLOY environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Open a terminal where you installed the Apps plugin and set the following variables to the AWS credentials just created and saved:
+
+- ``MM_APPS_DEPLOY_AWS_ACCESS_KEY``
+- ``MM_APPS_DEPLOY_AWS_SECRET_KEY``
+
+Set the following environment variables based on bucket name and region from Step 1:
+
+- ``MM_APPS_S3_BUCKET``
+- ``MM_APPS_AWS_REGION``
+
+Initialize the AWS resources
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following command will create Mattermost invocation credentials and policy for use with AWS.
+
+``go run ./cmd/appsctl aws init [flags...]``
+
+It will create or update:
+
+- An IAM user that will be used by the server to invoke the app (``mattermost-apps-invoke``).
+- An IAM group that the user belongs to, that will be used by the server to invoke the app (``mattermost-apps-invoke-group``).
+- An IAM policy used to control access to the Lambda and S3 resources, used by the invoke group (``mattermost-apps-invoke-policy``).
+- An IAM role used to execute app's functions (``mattermost-apps-execute-lambda-role``) with the ``AWSLambdaBasicExecutionRole`` attached to it.
+
+Optional Flags for the ``appsctl`` command:
+
+- ``--create-access-key`` create a new access key and print it out.
+- ``--create`` create resources that don't yet exist (user, group, role, access policy).
+- ``--group`` name the group to invoke function(s), default ``mattermost-apps-invoke-group``.
+- ``--policy`` name the policy used to invoke function(s), default ``mattermost-apps-invoke-policy``.
+- ``--user`` name the user to invoke the lambda function(s), default ``mattermost-apps-invoke``.
+
+The output of the command will contain two "Invoke" environment variables.
+
+2. Enable AWS Upstream for Mattermost Apps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable AWS Apps installation and use, the Mattermost server must be (re-)started with the following environment variables:
+
+- ``MM_APPS_AWS_ACCESS_KEY`` An AWS Access Key ID for ``mattermost-apps-invoke`` user. If ``appsctl aws init --create-access-key`` was used, it can be found (once!) in the command's output.
+- ``MM_APPS_AWS_SECRET_KEY`` The Secret Key for the access key above.
+- ``MM_APPS_AWS_REGION`` The AWS region to use.
+- ``MM_APPS_S3_BUCKET`` The name of the AWS bucket for static assets and manifests.
+
+Restart the Mattermost server to complete your Mattermost and AWS setup. You can now deploy an app to AWS.
+
+3. Deploy apps to AWS
+~~~~~~~~~~~~~~~~~~~~~
+
+Deploy an app to AWS
+^^^^^^^^^^^^^^^^^^^^
+
+To deploy AWS Apps from a bundle use ``appsctl aws deploy {aws-bundle.zip}`` command. It will deploy all necessary resources to AWS, update the invoke policy as needed, and "list" (upload the manifest of) the app in Mattermost server. ``--install`` can be used to automatically install the app once it's deployed.
+
+Flags:
+
+- ``--execute-role`` name of the role to use for executing the lambda function, default ``mattermost-apps-execute-lambda-role``
+- ``--install`` install the app onto the Mattermost server once it's been successfully deployed.
+- ``--policy`` name of the policy to use to invoke the lambda function, default ``mattermost-apps-invoke-policy``.
+- ``--update`` update the lambda function that already exists.
+
+The command requires that the following environment variables are set:
+
+- ``MM_SERVICESETTINGS_SITEURL`` must be set to where the Mattermost server APIs can be accessed.
+- ``MM_ADMIN_TOKEN`` must be set to access the Mattermost REST APIs.
+- ``MM_APPS_AWS_REGION`` must be set to the AWS region where the resources are deployed and accessed.
+- ``MM_APPS_S3_BUCKET`` must be the name of the S3 bucket used to store manifests and static assets.
+- ``MM_APPS_DEPLOY_AWS_ACCESS_KEY``, ``MM_APPS_DEPLOY_AWS_SECRET_KEY`` are the priviledged credentials used to deploy functions and files to AWS.
+- ``MM_APPS_AWS_ACCESS_KEY``, ``MM_APPS_AWS_SECRET_KEY`` are the "unprivileged" credentials used to invoke the functions, used only for the ``appsctl aws test`` command.
+
+Once deployed, apps can be installed interactively in Mattermost using ``/apps install listed`` command which will show all the deployed apps available for installation in Mattermost.
+
+Deployed app details
+~~~~~~~~~~~~~~~~~~~~
+
+AWS Lambda Functions Naming
+----------------------------
+
+AWS Lambda functions have semantic names, meaning that a function described in the ``manifest.json`` file translates to AWS as ``$appID_$appVersion_$functionName`` to avoid collisions with other apps' or other versions' functions. **appsctl** deploys lambda functions using this naming convention. For example, the name of a ``servicenow`` app's lambda function might be ``com-mattermost-servicenow_0-1-0_go-function``. **appsctl** handles the naming of AWS Lambda functions. The dedicated S3 bucket name is stored in the environment variable: ``MM_APPS_S3_BUCKET``.
+
+Storage of App Assets and Manifests
+------------------------------------
+
+The AWS S3 bucket mentioned above is used to store all app static assets and manifest files.
+
+All files in the static folder of the bundle are considered to be the app's static assets and are stored in the above-mentioned bucket. Stored assets also have semantic keys and are generated using the rule: ``static/$appID_$appVersion/filename``. For example, the ``servicenow`` app's static file key can be accessed at ``"static/com.mattermost.servicenow_0.1.0_app/photo.png"``.
+
+Storage of Manifest File
+------------------------
+
+The ``manifest.json`` file of an app is stored in the same S3 bucket with the key: ``manifests/$appID_$appVersion.json``.
+
+Flow of Deploying Custom Apps to AWS
+-------------------------------------
+
+.. image:: deploy-third-party-aws.png
+   :width: 800
+
+Deployment in Mattermost Cloud
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to be deployed in Mattermost Cloud, an app bundle is uploaded to the specific S3 bucket. On a new app release, a bundle is created by GitLab CI and uploaded to S3. The |Mattermost apps cloud deployer|, running as a k8s cron job every hour, detects the S3 upload, and creates appropriate lambda functions, assets, and manifest the same way the **appsclt** does for the third-party accounts.
+
+The deployer needs lambda function names, asset keys, and the manifest key to deploy the app. It calls the ``aws.GetProvisionDataFromFile(/PATH/TO/THE/APP/BUNDLE)`` from the Apps Plugin to get the deploy data. Same data can be generated using the command:
+
+``appsctl generate-terraform-data /PATH/TO/YOUR/APP/BUNDLE``
+
+Flow of deploying custom apps to AWS
+-------------------------------------
+
+.. image:: deploy-mm-aws.png
+   :width: 800
+
+.. |Mattermost apps cloud deployer| raw:: html
+
+    <a href="https://github.com/mattermost/mattermost-apps-cloud-deployer" target="_blank">Mattermost apps cloud deployer</a>
diff --git a/source/guides/deploy-http.rst b/source/guides/deploy-http.rst
@@ -0,0 +1,8 @@
+Deploy HTTP Apps
+================
+
+External service providers can offer "remote" apps already deployed as HTTP services.
+
+Internal organization-specific apps can also be developed and run as HTTP services on the existing hosting infrastructure, for example, using ``systemd``. It's important that your internal apps are only reachable by the Mattermost server, and not from the public internet.
+
+To install an HTTP app, use the ``/apps install http {URL-to-manifest.json}`` command in Mattermost.
diff --git a/source/guides/deploy-mattermost-apps.rst b/source/guides/deploy-mattermost-apps.rst
@@ -0,0 +1,39 @@
+App deployment
+==============
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+
+    Settings </guides/configure-app-framework>
+    HTTP </guides/deploy-http>
+    AWS </guides/deploy-aws>
+    Package Apps for AWS </guides/package-aws>
+    OpenFaaS </guides/deploy-openfaas>
+
+- In **Mattermost Cloud**, all apps are deployed to the Marketplace by Mattermost staff. They can be installed onto a specific Mattermost instance using the ``/apps install listed`` command. No special configuration is required; the ``/apps install`` command should be enabled and functional by default.
+
+- **Self-managed Mattermost** installations can use external Apps as HTTP services that have already been deployed, or can deploy App bundles on self-managed hosting or serverless platforms. Currently, `AWS Lambda <deploy-aws>`_, `OpenFaaS <deploy-openfaas>`_, and Kubeless deployments are supported. The `appsctl` command can be used to deploy app bundles to these environments.
+
+  Self-managed customers can also install external `HTTP <deploy-http>`_ apps, with no need to deploy them.
+
+  The ``appsctl`` CLI tool is provided to deploy AWS and OpenFaaS apps in self-managed environments. To install ``appsctl``, use the following command:
+
+  .. code-block:: shell
+
+      go install github.com/mattermost/mattermost-plugin-apps/cmd/appsctl@latest
+
+.. note::
+
+    If you have a self-hosted Mattermost instance running on AWS EC2, the default Golang version is 1.13.8.
+
+Because of this, the Golang install command will give an error stating:
+
+.. code-block:: shell
+
+    can't load package: package github.com/mattermost/mattermost-plugin-apps/cmd/appsctl@latest: cannot use path@version syntax in GOPATH mode
+
+To fix this, update your Golang version to the latest release and run the command again. When deploying to AWS, the ``appsctl`` binary is present in the ``Home`` directory inside the ``go/bin`` folder.
+
+To use ``appsctl``, run the following command: ``./go/bin/appsctl``
diff --git a/source/guides/deploy-mm-aws.png b/source/guides/deploy-mm-aws.png
diff --git a/source/guides/deploy-openfaas.rst b/source/guides/deploy-openfaas.rst
@@ -0,0 +1,56 @@
+Deploy Apps to OpenFaas and faasd
+=================================
+
+OpenFaaS Apps
+-------------
+
+What is OpenFaaS?
+~~~~~~~~~~~~~~~~~
+
+OpenFaaS makes it relatively simple to deploy both serverless functions and existing code in stateless containers on Kubernetes or directly on Linux hosts, on any public or private cloud. Learn more at |OpenFaas.com|.
+
+Package an App for OpenFaaS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For details on how to develop and package apps for AWS, see |serverless example|.
+
+Deploy with ``appsctl``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+An App designed and bundled for OpenFaaS can be deployed to the customer's own OpenFaaS or faasd environments, and then installed on a self-managed ("on-prem") Mattermost server, using the ``appsctl openfaas deploy`` command.
+
+This command requires that |faas-cli| is installed and configured, with credentials sufficiently privileged to deploy functions.
+
+OpenFaaS requires a |docker registry| to pass the images that it builds to the function instances, so ``docker`` must have been configured, and ``docker login`` done, with sufficient credentials to push to the registry of choice.
+
+To deploy OpenFaaS Apps use ``appsctl openfaas deploy {openfaas-bundle.zip}`` command. It will deploy all functions in the bundle, and "list" (upload the manifest of) the app in Mattermost server. ``--install`` can be used to automatically install the app once it's deployed.
+
+**Flags:**
+
+- ``--docker-registry``: the docker registry name (will be used as a prefix for the image name) to push the function images to.
+- ``--install``: install the app onto the Mattermost server once it's been successfully deployed.
+- ``--update``: update the function that already exists.
+
+The command requires that the following environment variables are set:
+
+- ``MM_SERVICESETTINGS_SITEURL``: must be set to where the Mattermost server APIs can be accessed.
+- ``MM_ADMIN_TOKEN``: must be set to access the Mattermost REST APIs.
+- ``OPENFAAS_URL``: must be set to the admin (root) URL of the OpenFaaS installation.
+
+Once deployed, apps can be installed interactively in Mattermost using ``/apps install listed`` command.
+
+.. |OpenFaas.com| raw:: html
+
+    <a href="https://www.openfaas.com" target="_blank">OpenFaas.com</a>
+
+.. |serverless example| raw:: html
+
+    <a href="https://developers.mattermost.com/integrate/apps/quickstart/quick-start-serverless" target="_blank">serverless example</a>
+
+.. |faas-cli| raw:: html
+
+    <a href="https://github.com/openfaas/faas-cli" target="_blank">faas-cli</a>
+
+.. |docker registry| raw:: html
+
+    <a href="https://docs.docker.com/registry/" target="_blank">docker registry</a>
diff --git a/source/guides/deploy-third-party-aws.png b/source/guides/deploy-third-party-aws.png
diff --git a/source/guides/deployment.rst b/source/guides/deployment.rst
@@ -11,20 +11,21 @@ Learn how to install, deploy, and scale Mattermost for teams and organizations o
   :hidden:
   :titlesonly:
 
-  Prepare your Mattermost database </install/prepare-mattermost-database>
-  Deploy on Ubuntu </install/install-ubuntu>
-  Deploy using Docker </install/install-docker>
-  Deploy with a tarball </install/install-tar>
-  Deploy using Omnibus </install/installing-mattermost-omnibus>
-  Deploy using Kubernetes </install/install-kubernetes>
-  Deploy on Red Hat </install/install-rhel-8>
-  Prepare for your Mattermost deployment </guides/prepare-for-your-mattermost-deployment>
-  Deployment guides </guides/deployment-guides>
-  Upgrade Mattermost </guides/upgrade-mattermost>
-  Scale Mattermost </guides/scale-mattermost>
-  Deployment troubleshooting </guides/deployment-troubleshooting>
-  Changelogs </guides/changelogs>
-  Additional server installation guides </guides/additional-server-installation-guides>
+    Prepare your Mattermost database </install/prepare-mattermost-database>
+    Deploy on Ubuntu </install/install-ubuntu>
+    Deploy using Docker </install/install-docker>
+    Deploy with a tarball </install/install-tar>
+    Deploy using Omnibus </install/installing-mattermost-omnibus>
+    Deploy using Kubernetes </install/install-kubernetes>
+    Deploy on Red Hat </install/install-rhel-8>
+    Prepare for your Mattermost deployment </guides/prepare-for-your-mattermost-deployment>
+    Deployment guides </guides/deployment-guides>
+    Deploy Mattermost Apps </guides/deploy-mattermost-apps>
+    Upgrade Mattermost </guides/upgrade-mattermost>
+    Scale Mattermost </guides/scale-mattermost>
+    Deployment troubleshooting </guides/deployment-troubleshooting>
+    Changelogs </guides/changelogs>
+    Additional server installation guides </guides/additional-server-installation-guides>
 
 .. tip::
 
@@ -39,7 +40,8 @@ Learn how to install, deploy, and scale Mattermost for teams and organizations o
 * :doc:`Deploy using Omnibus </install/installing-mattermost-omnibus>` - An entire Mattermost installation on a single server.
 * :doc:`Deploy using Kubernetes </install/install-kubernetes>` - Install using the Mattermost Helm Chart or Operator and simplified updates.
 * :doc:`Deploy on Red Hat </install/install-rhel-8>` - Support for all current Red Hat Enterprise Linux platforms with a tarball.
-* :doc:`Deployment guides </guides/deployment-guides>` - for administrators who are ready to integrate Mattermost with their organization’s IT infrastructure. 
+* :doc:`Deployment guides </guides/deployment-guides>` - for administrators who are ready to integrate Mattermost with their organization’s IT infrastructure.
+* :doc:`Deploy Mattermost Apps </guides/deploy-mattermost-apps>` - Learn how to deploy Mattermost Apps to your server.
 * :doc:`Prepare for your Mattermost deployment </guides/prepare-for-your-mattermost-deployment>` - Review software and hardware requirements for Mattermost server, and plan out your Mattermost rollout.
 * :doc:`Upgrade Mattermost </guides/upgrade-mattermost>` - Learn how to stay up to date with the latest features and improvements.
 * :doc:`Scale Mattermost </guides/scale-mattermost>` - Learn how to scale and monitor your Mattermost deployment.