snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/develop/contribute/more-info/mobile/push-notifications/android.md

@@ -0,0 +1,42 @@
+---
+title: "Android push notifications"
+sidebar_position: 1
+---
+
+Push notifications on Android are managed and dispatched using [Firebase Cloud Messaging (FCM)](http://firebase.google.com/docs/cloud-messaging/)
+
+- Create a Firebase project within the [Firebase Console](https://console.firebase.google.com).
+
+- Click **Add Project**
+   ![image](/img/mobile/firebase_console.png)
+
+- Enter the project name, project ID and Country
+
+- Click **CREATE PROJECT**
+
+   ![image](/img/mobile/firebase_project.png)
+
+Once the project is created you'll be redirected to the Firebase project
+dashboard
+
+![image](/img/mobile/firebase_dashboard.png)
+
+- Click **Add Firebase to your Android App**
+- Enter the package ID of your custom Mattermost app as the **Android package name**.
+- Enter an **App nickname** so you can identify it with ease
+- Click **REGISTER APP**
+- Once the app has been registered, download the **google-services.json** file which will be used later
+
+- Click **CONTINUE** and then **FINISH**
+   ![image](/img/mobile/firebase_register_app.png)
+   ![image](/img/mobile/firebase_google_services.png)
+   ![image](/img/mobile/firebase_sdk.png)
+
+Now that you have created the Firebase project and the app and
+downloaded the *google-services.json* file, you need to make some
+changes in the project.
+
+- Replace `android/app/google-services.json` with the one you downloaded earlier
+
+At this point, you can build the Mattermost app for Android and setup the [Mattermost Push Notification Service](/developers/contribute/more-info/mobile/push-notifications/service).
+

docs/develop/contribute/more-info/mobile/push-notifications/corporate-proxy.md

@@ -0,0 +1,33 @@
+---
+title: "Corporate proxy"
+sidebar_position: 4
+---
+
+When your IT policy requires a corporate proxy to scan and audit all outbound traffic the following options are available:
+
+###### 1. Deploy Mattermost with connection restricted post-proxy relay in DMZ or a trusted cloud environment
+
+Some legacy corporate proxy configurations may be incompatible with the requirements of modern mobile architectures, such as the requirement of HTTP/2 requests from Apple to send push notifications to iOS devices.
+
+In this case, a **post-proxy relay** (which accepts network traffic from a corporate proxy such as NGINX, and transmits it to the final destination) can be deployed to take messages from the Mattermost server passing through your corporate IT proxy in the incompatible format, e.g. HTTP/1.1, transform it to HTTP/2 and relay it to its final destination, either to the [Apple Push Notification Service (APNS)](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW1) and [Google Fire Cloud Messaging (FCM)](https://firebase.google.com/docs/cloud-messaging) services.
+
+The **post-proxy relay** [can be configured using the Mattermost Push Proxy installation guide](/developers/contribute/more-info/mobile/push-notifications/service) with connection restrictions to meet your custom security and compliance requirements.
+
+You can also host in a trusted cloud environment such as AWS or Azure in place of a DMZ (this option may depend on your organization's internal policies).
+
+![image](/img/mobile/post-proxy-relay.png)
+
+###### 2. Whitelist Mattermost push notification proxy to bypass your corporate proxy server
+
+Depending on your internal IT policy and approved waivers/exceptions, you may choose to deploy the [Mattermost Push Proxy](/developers/contribute/more-info/mobile/push-notifications/service) to connect directly to [Apple Push Notification Service (APNS)](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html#//apple_ref/doc/uid/TP40008194-CH8-SW1) without your corporate proxy.
+
+You will need to [whitelist one subdomain and one port from Apple](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CommunicatingwithAPNs.html#//apple_ref/doc/uid/TP40008194-CH11-SW1) for this option:
+
+ - Development server: `api.development.push.apple.com:443`
+ - Production server: `api.push.apple.com:443`
+
+###### 3. Run App Store versions of the Mattermost mobile apps
+
+You can use the mobile applications hosted by Mattermost in the [Apple App Store](https://apps.apple.com/ca/app/mattermost/id1257222717) or [Google Play Store](https://play.google.com/store/apps/details?id=com.mattermost.rn) and connect with [Mattermost Hosted Push Notification Service (HPNS)](https://docs.mattermost.com/deploy/mobile-hpns.html) through your corporate proxy.
+
+The use of hosted applications by Mattermost [can be deployed with Enterprise Mobility Management solutions via AppConfig](https://docs.mattermost.com/deploy/mobile-appconfig.html). Wrapping is not supported with this option.

docs/develop/contribute/more-info/mobile/push-notifications/index.md

@@ -0,0 +1,13 @@
+---
+title: "Set up push notifications"
+sidebar_position: 3
+---
+
+When building a custom version of the Mattermost mobile app, you will also need to host your own [Mattermost Push Notification Service](https://github.com/mattermost/mattermost-push-proxy/releases) and make a few modifications to your Mattermost mobile app to be able to get push notifications.
+
+1. Setup the custom mobile apps to receive push notifications
+    - [Android](/developers/contribute/more-info/mobile/push-notifications/android)
+    - [iOS](/developers/contribute/more-info/mobile/push-notifications/ios)
+2. [Setup the Mattermost push notification service](/developers/contribute/more-info/mobile/push-notifications/service)
+
+If the use of a proxy server is required by your IT policy, see the [corporate proxy](/corporate-proxy) page.

docs/develop/contribute/more-info/mobile/push-notifications/ios.md

@@ -0,0 +1,50 @@
+---
+title: "iOS push notifications"
+sidebar_position: 2
+---
+
+## Generate APNs Auth Key
+
+To deliver push notifications on iOS, you need to authenticate with **Apple Push Notification service (APNs)**.  
+Mattermost recommends using **token-based authentication** with an APNs Auth Key (`.p8`) instead of certificates.
+
+---
+
+### Prerequisites
+
+- Apple Developer Program account  
+- Registered iOS app Bundle ID with **Push Notifications** capability enabled  
+
+---
+
+### 1. Create an APNs Auth Key
+
+1. Sign in to [Apple Developer: Keys](https://developer.apple.com/account/resources/authkeys/list).
+2. Click **+** to register a new key.
+   ![Apple Developer register new key](/img/mobile/ios-register-key.png)
+3. **Enter a Key Name** to easily identify it later (e.g., *Mattermost Push Proxy*).
+   ![Enter key name](/img/mobile/ios-key-name.png)
+4. **Enable APNs** by checking the **Apple Push Notifications service (APNs)** box and click **Configure** to configure the key.
+   ![Enable APNs](/img/mobile/ios-enable-apns.png)
+5. On the **Configure Key** screen:
+   - Select an **Environment**: *Sandbox*, *Production*, or *Sandbox & Production*.
+   - Choose a **Key Restriction**: *Team Scoped (All Topics)* or *Topic Specific*. 
+   ![Configure APNs key](/img/mobile/ios-configure-apns.png)
+   - If you select *Topic Specific*, add the topics (App IDs) you want to associate.
+   ![Add topics](/img/mobile/ios-add-topics.png)
+6. Click **Save**, then **Continue**.
+7. Review the Key details and click **Register**.
+8. Download the generated file `AuthKey_XXXXXXXXXX.p8` and store it securely.
+   > You can only download the file once.
+9. Note the following values:
+   - **Key ID** (from the Keys list)
+   - **Team ID** (from your Apple Developer Membership)
+   - **Bundle ID** (your app identifier, used as the APNs topic)
+
+![Apple Developer key list](/img/mobile/ios-key-list.png)
+
+---
+
+### 2. Next Steps
+
+Once you’ve generated your APNs Auth Key and collected the Key ID, Team ID, and Bundle ID, continue to the [Push Notification Service setup](/developers/contribute/more-info/mobile/push-notifications/service) page to configure the Mattermost Push Notification Service (MPNS).

docs/develop/contribute/more-info/mobile/push-notifications/service.md

@@ -0,0 +1,174 @@
+---
+title: "Push notification service"
+sidebar_position: 3
+---
+
+Now that the app can receive push notifications, we need to make sure that the Mattermost Push Notification Service is able to send the notification to the device. This guide will focus on installing and configuring the push notification service.
+
+### Requirements
+
+- A Linux or FreeBSD box server with at least 1GB of memory.
+- A copy of the [Mattermost Push Notification Service](https://github.com/mattermost/mattermost-push-proxy/releases).
+- [Custom Android and/or iOS](/developers/contribute/more-info/mobile/build-your-own) Mattermost mobile apps.
+- An APNs Auth Key (`.p8`) obtained by following the [iOS Push Notifications guide](/developers/contribute/more-info/mobile/push-notifications/ios).
+- A Firebase Cloud Messaging Server key obtained by following the [Android Push Notifications guide](/developers/contribute/more-info/mobile/push-notifications/android).
+
+## Install and upgrade
+
+For the sake of making this guide simple we located the files at `/home/ubuntu/mattermost-push-proxy`. We've also elected to run the Push Notification Service as the `ubuntu` account for simplicity. We **recommend** setting up and running the service under a `mattermost-push-proxy` user account with limited permissions.
+
+1. Download the latest Mattermost Push Notification Service:
+
+    `wget https://github.com/mattermost/mattermost-push-proxy/releases/download/vX.X.X/mattermost-push-proxy-linux-amd64.tar.gz`  
+    or  
+    `wget https://github.com/mattermost/mattermost-push-proxy/releases/download/vX.X.X/mattermost-push-proxy-freebsd-amd64.tar.gz` 
+
+```text
+In this command, `vX.X.X` refers to the release version you want to download. See [Mattermost Push Notification Service releases](https://github.com/mattermost/mattermost-push-proxy/releases).
+```
+
+2. If you're upgrading a previous version of the Mattermost Push Notification Service make sure to back up your `mattermost-push-proxy.json` file before continuing.
+
+3. Unzip the downloaded Mattermost Push Notification Service using:  
+    `tar -xvzf mattermost-push-proxy-linux-amd64.tar.gz`  
+    or   
+    `tar -xvzf mattermost-push-proxy-freebsd-amd64.tar.gz`
+
+4. Configure the Mattermost Push Notification service by editing the `mattermost-push-proxy.json` file at `/home/ubuntu/mattermost-push-proxy/config`. Follow the steps in the [Android](#set-up-mattermost-push-notification-service-to-send-android-push-notifications)
+    and [iOS](#set-up-mattermost-push-notification-service-to-send-ios-push-notifications) sections to replace the values in the config file.
+
+5. Create a systemd unit file to manage the Mattermost Push Notification Services with systemd and log all output of the service to `/var/log/syslog` by running this command as root.
+    ```bash
+    echo "[Unit]
+    Description=Mattermost Push Notification Service
+
+    [Service]
+    Type=oneshot
+    ExecStart=/bin/sh -c '/home/ubuntu/mattermost-push-proxy/bin/mattermost-push-proxy | logger'
+    WorkingDirectory=/home/ubuntu/mattermost-push-proxy
+
+    [Install]
+    WantedBy=multi-user.target" >> /etc/systemd/system/mattermost-push-proxy.service
+    ```
+
+   To route the traffic through a separate proxy server, add `Environment="HTTP_PROXY=<http://server>"` under the `[Service]` section of the file. If you have an HTTPS server, then use `HTTPS_PROXY`. If you set both then `HTTPS_PROXY` will take higher priority than `HTTP_PROXY`.
+
+6. Start the service with `sudo systemctl start mattermost-push-proxy` or restart with `sudo systemctl restart mattermost-push-proxy`. Use `sudo systemctl enable mattermost-push-proxy` to have systemd start the service on boot.
+
+### Set up Mattermost push notification service to send Android push notifications
+
+- Go to the [Firebase Console](https://console.firebase.google.com) and select the project you've created. Once in the dashboard, go to the project settings and select **Service Accounts**.
+![image](/img/mobile/firebase_settings.png)
+![image](/img/mobile/firebase_cloud_messaging.png)
+
+- Click on **Generate new private key** and store the downloaded file.
+![image](/img/mobile/firebase_server_key.png)
+
+- Open the **mattermost-push-proxy.json** file in the `mattermost-push-proxy/config` directory and look for the "ServiceFileLocation" entry under "AndroidPushSettings". Paste the location of the file as its value.
+  ```
+  "ServiceFileLocation": "/path/to/downloaded_file"
+  ```
+
+### Set up Mattermost push notification service to send iOS push notifications
+
+Instead of certificates, we now recommend using an **APNs Auth Key (`.p8`)** to authenticate with Apple Push Notification service (APNs).  
+If you haven’t generated your key yet, see [Generate an APNs Auth Key](/developers/contribute/more-info/mobile/push-notifications/ios).
+
+- Open the **mattermost-push-proxy.json** file under the `mattermost-push-proxy/config` directory and configure it with your key details:
+
+  ```json
+  "ApplePushSettings":[
+      {
+          "Type":"apple_rn",
+          "ApplePushUseDevelopment":true,
+          "ApplePushTopic":"your.bundle.id",
+          "AppleAuthKeyFile":"./config/beta/YourAuthKeyFile.p8",
+          "AppleAuthKeyID":"YourAuthKeyID",
+          "AppleTeamID":"YourAppleTeamID"
+      }
+  ],
+  ```
+- **ApplePushTopic**: Your app’s bundle ID (APNs topic).  
+- **AppleAuthKeyFile**: Path to the `.p8` file.  
+- **AppleAuthKeyID**: Key ID from Apple Developer portal.  
+- **AppleTeamID**: Team ID from Apple Developer Membership.  
+- **ApplePushUseDevelopment**: `true` for sandbox APNs, `false` for production.
+
+
+<Note>
+If you are migrating from certificate-based authentication, you can remove the `ApplePushCertPrivate` field and replace it with the new `AppleAuthKeyFile`, `AppleAuthKeyID`, and `AppleTeamID` values.
+</Note>
+
+
+### Configure the Mattermost Server to use the Mattermost push notification service
+
+- In your Mattermost instance, enable mobile push notifications.
+    * Go to **System Console > Notifications > Mobile Push**.
+    * Under **Send Push Notifications**, select **Manually enter Push Notification Service location**.
+    * Enter the location of your Mattermost Push Notification Service in the **Push Notification Server** field.
+
+      ![image](/img/mobile/manual_mpns.png)
+
+- (Optional) Customize mobile push notification contents.
+    * Go to **System Console > Notifications > Mobile Push**.
+    * Select an option for **Push Notification Contents** to specify what type of information to include in the push notifications.
+    * Most deployments choose to include the full message snippet in push notifications unless they have policies against it to protect confidential information.
+
+      ![image](/img/mobile/push_contents.png)
+
+- Finally, start your Mattermost Push Notification Service, and your app should start receiving push notifications.
+
+### Test the Mattermost push notification service
+
+* Verify that the server is functioning normally and test the push notification using curl:
+  `curl http://127.0.0.1:8066/api/v1/send_push -X POST -H "Content-Type: application/json" -d '{"type": "message", "message": "test", "badge": 1, "platform": "PLATFORM", "server_id": "MATTERMOST_DIAG_ID", "device_id": "DEVICE_ID", "channel_id": "CHANNEL_ID"}'`
+
+  * Replace `MATTERMOST_DIAG_ID` with the value found by running the SQL query:
+    ```sql
+    SELECT * FROM Systems WHERE Name = 'DiagnosticId';
+    ```
+  * Replace `DEVICE_ID` with your device ID, which can be found using (where `your_email@example.com` is the email address of the user you are logged in as):
+    ```sql
+    SELECT
+       Email, DeviceId
+    FROM
+       Sessions,
+       Users
+    WHERE
+       Sessions.UserId = Users.Id
+          AND DeviceId != ''
+          AND Email = 'your_email@example.com';
+    ```
+  * Replace `CHANNEL_ID` with the Town Square channel ID, which can be found using:
+    ```sql
+    SELECT Id FROM Channels WHERE DisplayName = 'Town Square';
+    ```
+  
+<Note title="Migration">
+Remove the `apple:`, `apple_rn`, `android:` or `android_rn:` prefix from your device ID before replacing `DEVICE_ID`. Use that prefix as the `PLATFORM` (make sure to remove the ":").
+</Note>
+
+* You can also verify push notifications are working by opening your Mattermost site and mentioning a user who has push notifications enabled in **Settings > Notifications > Mobile Push Notifications**.
+
+To view the log file, use:
+
+```bash
+$ sudo tail -n 1000 /var/log/upstart/mattermost-push-proxy.log
+```
+
+<Note title="Note">
+Note that device IDs can change somewhat frequently, as they are tied to a device session. If you're having trouble, double-check the latest device IDs by re-running the above queries.
+</Note>
+
+
+### Troubleshooting
+
+##### DeviceTokenNotForTopic
+
+**For iOS / Apple Push Notifications**: If the logs are reflecting DeviceTokenNotForTopic (error 400) this may be because you're using an older / previous Device ID. Re-run the queries you need to get device IDs and test.
+
+This could also be because you generated a key for the wrong bundle ID. The bundle ID used in `mattermost-push-proxy.json` should be the same one as the app, and should be for the same app it was generated for.
+
+### Reporting issues
+
+For issues with repro steps, please report to https://github.com/mattermost/mattermost/issues