Prepare Hub guided self-hosting docs for the next release (#3342)

* docs(hub): drop the manual auth secret from self-hosting setup Hub generates its authentication secret on first start and stores it in the database it is already using, so self-hosters no longer run openssl or carry PASEO_HUB_AUTH_SECRET between restarts. The variable stays as an override for deployments that must supply the secret from a platform secret store; Hub uses it without persisting it, so removing it resumes the stored value. Also corrects a claim that predates this change: rotating the secret does not invalidate execution credentials already issued. Hub verifies those against persisted hashes rather than the secret, so only browser sessions end. Documentation companion to https://github.com/getpaseo/hub/pull/50. * docs(hub): lead with the local guided setup * docs(hub): document XDG data directory * docs: make Hub self-hosting the quickstart
2026-08-20 14:16:01 +02:00
parent c6b04f302a
commit 9163aed3f1
9 changed files with 290 additions and 315 deletions
@@ -1,6 +1,6 @@
 ---
 title: Slack for Hub
-description: Create the Slack app your Hub uses, connect a workspace, and write Slack triggers.
+description: Connect Slack over Socket Mode, or use webhooks from a public Hub.
 nav: Slack app
 order: 76
 category: Hub
@@ -8,62 +8,72 @@ category: Hub

 # Slack for Hub

-Hub receives Slack mentions over the Events API. Socket Mode is not used, so your Hub needs a publicly reachable HTTPS origin with a valid certificate. See [Provider URLs](/docs/hub/self-hosting#provider-urls).
+Slack can reach Hub in two ways:

-## Create the app
+| Transport   | Public HTTPS required | Best for                                |
+| ----------- | --------------------- | --------------------------------------- |
+| Socket Mode | No                    | Local, personal, and single-process Hub |
+| Webhooks    | Yes                   | Public server deployments               |

-Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App → From a manifest**, and paste this after replacing `hub.example.com` with your `PASEO_HUB_APP_URL`:
+Socket Mode is the default in browser setup. Both transports produce the same `slack.mention` triggers and thread replies.

-```yaml
-display_information:
-  name: Paseo
-features:
-  bot_user:
-    display_name: Paseo
-    always_online: false
-oauth_config:
-  redirect_urls:
-    - https://hub.example.com/api/integrations/slack/callback
-  scopes:
-    bot:
-      - app_mentions:read
-      - chat:write
-      - reactions:write
-settings:
-  event_subscriptions:
-    request_url: https://hub.example.com/api/integrations/slack/events
-    bot_events:
-      - app_mention
-  interactivity:
-    is_enabled: false
-  org_deploy_enabled: false
-  socket_mode_enabled: false
-  token_rotation_enabled: false
-```
+## Set up Socket Mode

-## Configure Hub
+Open **Apps → Slack** in Hub and keep **Socket Mode** selected. Hub gives you the Slack manifest and the exact steps to:

-From **Basic Information → App Credentials**, copy:
+1. Create the Slack app from the manifest.
+2. Generate an App-level token with `connections:write`.
+3. Install the app and copy its Bot User OAuth Token.

-| Value          | Environment variable   |
-| -------------- | ---------------------- |
-| App ID         | `SLACK_APP_ID`         |
-| Client ID      | `SLACK_CLIENT_ID`      |
-| Client Secret  | `SLACK_CLIENT_SECRET`  |
-| Signing Secret | `SLACK_SIGNING_SECRET` |
+Paste both tokens into Hub and choose **Connect Slack**. Hub verifies the installation, saves it for the active organization, and opens the outbound Socket Mode connection.

-Restart Hub before Slack verifies the request URL. Hub needs the signing secret to answer the verification challenge.
-
-## Connect
-
-Open **Connections → Slack → Connect**, pick the workspace, and allow it.
-
-Use Hub's button, not Slack's **Install to Workspace**. The install has to start from Hub so the workspace binds to your organization.
-
-Then invite the bot to each channel it should watch:
+Invite the bot to each channel it should watch:

 ```text
 /invite @Paseo
 ```

-Now write a trigger: [Slack triggers](/docs/hub/triggers/slack).
+Now write a [Slack trigger](/docs/hub/triggers/slack).
+
+Socket Mode holds one live connection in the Hub process. Run one Hub process for this transport and keep it running; events that arrive while it is stopped are missed.
+
+## Use webhooks
+
+Choose **Webhooks** when Slack should send events to a stable public Hub. Hub must be open at its public HTTPS address before setup so the generated redirect and request URLs are correct.
+
+The Apps guide gives you a webhook manifest and asks for the App ID, Client ID, Client Secret, and Signing Secret. Saving continues to Slack so you can install the app into a workspace.
+
+Slack calls:
+
+| Provider setting | Hub URL                                               |
+| ---------------- | ----------------------------------------------------- |
+| Redirect URL     | `<PASEO_HUB_APP_URL>/api/integrations/slack/callback` |
+| Request URL      | `<PASEO_HUB_APP_URL>/api/integrations/slack/events`   |
+
+Start the installation from Hub. An installation started only from Slack is not bound to a Hub organization.
+
+## Configure from environment
+
+Deployments that keep app secrets outside Hub can use one complete transport configuration.
+
+Socket Mode:
+
+```dotenv
+SLACK_TRANSPORT=socket
+SLACK_APP_ID=A01234567
+SLACK_APP_TOKEN=xapp-...
+```
+
+The Bot User OAuth Token remains attached to each saved Slack workspace connection; it is not part of the Socket Mode environment configuration.
+
+Webhooks:
+
+```dotenv
+SLACK_TRANSPORT=webhook
+SLACK_APP_ID=A01234567
+SLACK_CLIENT_ID=...
+SLACK_CLIENT_SECRET=...
+SLACK_SIGNING_SECRET=...
+```
+
+Environment configuration takes precedence over a saved Slack app and appears as **Managed by environment** under **Apps**.