Adding documentation about using SingleInstance with snap and flatpak (#3350)

Co-authored-by: Fabian-Lars <[email protected]>

Author: charlesschaefer

package.json

@@ -43,7 +43,7 @@
     "starlight-blog": "^0.15.0",
     "starlight-links-validator": "^0.13.0"
   },
-  "packageManager": "pnpm@10.11.0",
+  "packageManager": "pnpm@10.12.1",
   "engines": {
     "pnpm": "^10.0.0"
   },

src/content/docs/distribute/snapcraft.mdx

@@ -84,6 +84,24 @@ apps:
     #  - network
     # Add whatever plugs you need here, see https://snapcraft.io/docs/snapcraft-interfaces for more info.
     # The gnome extension already includes [ desktop, desktop-legacy, gsettings, opengl, wayland, x11, mount-observe, calendar-service ]
+    #  - single-instance-plug # add this if you're using the single-instance plugin
+    #slots:
+    # Add the slots you need to expose to other snaps
+    #  - single-instance-plug # add this if you're using the single-instance plugin
+
+# Add these lines only if you're using the single-instance plugin
+# Check https://v2.tauri.app/plugin/single-instance/ for details
+#slots:
+#  single-instance:
+#    interface: dbus
+#    bus: session
+#    name: org.net_mydomain_MyApp.SingleInstance # Remember to change net_mydomain_MyApp to your app ID with "_" instead of "." and "-"
+#
+#plugs:
+#  single-instance-plug:
+#    interface: dbus
+#    bus: session
+#    name: org.net_mydomain_MyApp.SingleInstance # Remember to change net_mydomain_MyApp to your app ID with "_" instead of "." and "-"
 
 package-repositories:
   - type: apt

src/content/docs/plugin/single-instance.mdx

@@ -122,3 +122,78 @@ pub fn run() {
         .expect("error while running tauri application");
 }
 ```
+
+## Usage in Snap and Flatpak
+
+On Linux the Single Instance plugin uses DBus to ensure that there will be only one instance running. It does so by publishing a service to DBus when the first instance starts running.
+Then, the following instances will try to publish the same service and, if it is already published, they will send a request to the service to notify the first instance, and exit right away.
+
+Despite this working pretty well when your app is bundled as a deb or rpm package or an AppImage, it won't work as intended for snap or flatpak packages by default because these packages run in a constrained sandboxed environment, where most of the communication to DBus services will be blocked if not explicitly declared on the packaging manifest.
+
+Here's a guide that shows how to declare the needed permissions to enable the Single Instance for snap and flatpak packages:
+
+### Getting your app ID
+
+The Single Instance plugin will publish a service named `org.{id}.SingleInstance`.
+
+`{id}` will be the `identifier` from your `tauri.conf.json` file, but with with dots (`.`) and dashes (`-`) replaced by underline (`_`).
+
+For example, if your identifier is `net.mydomain.MyApp`:
+
+- `net_mydomain_MyApp` will be your app `{id}`
+- `org.net_mydomain_MyApp.SingleInstance` will be your app SingleInstance service name
+
+You will need the service name to authorize your app to use the DBus service on snap and flatpak manifests, as seen below.
+
+### Snap
+
+In your snapcraft.yml file, declare a plug and a slot for the single instance service, and use both on your app declaration:
+
+```yaml title="snapcraft.yml"
+# ...
+slots:
+  single-instance:
+    interface: dbus
+    bus: session
+    name: org.net_mydomain_MyApp.SingleInstance # Remember to change net_mydomain_MyApp to your app ID
+
+plugs:
+  single-instance-plug:
+    interface: dbus
+    bus: session
+    name: org.net_mydomain_MyApp.SingleInstance # Remember to change net_mydomain_MyApp to your app ID
+
+# .....
+apps:
+  my-app:
+    # ...
+    plugs:
+      # ....
+      - single-instance-plug
+    slots:
+      # ...
+      - single-instance
+
+    # ....
+```
+
+This will allow your app to send and receive requests from/to the DBus service as expected by the Single Instance plugin.
+
+### Flatpak
+
+In your flatpak manifest file (your.app.id.yml or your.app.id.json), declare a `--talk-name` and a `--own-name` finish args with the service name:
+
+```yaml title="net.mydomain.MyApp.yml"
+# ...
+finish-args:
+  - --socket=wayland
+  - --socket=fallback-x11
+  - --device=dri
+  - --share=ipc
+  # ....
+  - --talk-name=org.net_mydomain_MyApp.SingleInstance # Remember to change net_mydomain_MyApp to your app ID
+  - --own-name=org.net_mydomain_MyApp.SingleInstance # Remember to change net_mydomain_MyApp to your app ID
+# ...
+```
+
+This will allow your app to send and receive requests from/to the DBus service as expected by the Single Instance plugin.