jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(hub): align public docs with v0.3 (#3152)

Browse Source 
* docs(hub): align public docs with v0.3

Bring the public workflow, API, authority, activity, and self-hosting guidance in line with the released Hub contracts. Clarify the public HTTPS boundary required by provider events while keeping Hub and PostgreSQL private.

* docs(hub): clarify daemon logout scope

* docs(hub): restore Compose path and simplify TLS guidance

* docs(hub): link the single-repo-team-bot example
This commit is contained in:
Mohamed Boudra
2026-08-10 16:13:51 +02:00
committed by GitHub
parent 48e65b407f
commit 42f1d0b289
14 changed files with 149 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public-docs/hub/self-hosting/github-app.md
+2
View File
@@ -16,6 +16,8 @@ Go to **Settings → Developer settings → GitHub Apps → New GitHub App** on
Replace `hub.example.com` with your `PASEO_HUB_APP_URL`.
The webhook URL must be reachable from GitHub. Keep GitHub's default SSL verification enabled; see [Provider URLs](/docs/hub/self-hosting#provider-urls).
| Setting | Value |
| ------------------ | ---------------------------------------------------------- |
| Homepage URL | `https://hub.example.com` |
public-docs/hub/self-hosting/index.md
+42 -6
View File
@@ -20,11 +20,11 @@ Migrations run automatically at startup. Hub does not start listening when a mig
Hub has one public URL and one persistent application secret:
| Variable | Purpose |
| ----------------------- | ------------------------------------------------------------------ |
| `PASEO_HUB_APP_URL` | Public origin used by the dashboard, authentication, and callbacks |
| `PASEO_HUB_AUTH_SECRET` | Protects browser sessions and derives execution credentials |
| `DATABASE_URL` | PostgreSQL connection string |
| Variable | Purpose |
| ----------------------- | ---------------------------------------------------------------------------- |
| `PASEO_HUB_APP_URL` | Public origin used by the dashboard, authentication, callbacks, and webhooks |
| `PASEO_HUB_AUTH_SECRET` | Protects browser sessions and derives execution credentials |
| `DATABASE_URL` | PostgreSQL connection string |
Generate `PASEO_HUB_AUTH_SECRET` once and keep it across restarts:
@@ -89,7 +89,26 @@ docker compose up -d
The stack publishes Hub on port `3000` and stores PostgreSQL data in a named volume. The Hub image is `ghcr.io/getpaseo/hub:latest`.
When a reverse proxy terminates HTTPS, set `PASEO_HUB_TRUSTED_CLIENT_IP_HEADER` to the header carrying the original client IP.
### HTTPS with Caddy
Compose serves plain HTTP on port `3000`. Run Caddy on the same host to terminate TLS:
```caddyfile
hub.example.com {
reverse_proxy 127.0.0.1:3000
}
```
Point `hub.example.com` at the host and open ports 80 and 443. Caddy [obtains and renews the certificate](https://caddyserver.com/docs/automatic-https).
Then set in `.env`:
```dotenv
PASEO_HUB_APP_URL=https://hub.example.com
PASEO_HUB_TRUSTED_CLIENT_IP_HEADER=x-forwarded-for
```
To keep port `3000` off the public interface, change the `hub` port in `compose.yml` to `"127.0.0.1:3000:3000"`.
## Fly
@@ -122,6 +141,23 @@ fly deploy -a your-hub \
Keep one machine running. Hub holds the Discord gateway connection and dispatches events to daemons, so a stopped machine misses events.
## Provider URLs
Slack and GitHub call Hub at `PASEO_HUB_APP_URL`:
| Provider setting | URL |
| ---------------------------- | ------------------------------------------------------ |
| GitHub webhook | `<PASEO_HUB_APP_URL>/webhook` |
| GitHub OAuth callback | `<PASEO_HUB_APP_URL>/api/integrations/github/callback` |
| Slack Events API request URL | `<PASEO_HUB_APP_URL>/api/integrations/slack/events` |
| Slack OAuth callback | `<PASEO_HUB_APP_URL>/api/integrations/slack/callback` |
Slack requires the Events API request URL to be publicly reachable over HTTPS with a valid certificate, and its [OAuth redirect URL](https://docs.slack.dev/authentication/installing-with-oauth/) must use HTTPS. See Slack's [HTTP request URL](https://docs.slack.dev/apis/events-api/using-http-request-urls/) requirements.
GitHub must reach the webhook URL and [verifies SSL certificates](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks#use-https-and-ssl-verification) by default.
A Hub on `localhost` or a LAN address still runs manual and daemon workflows, but Slack and GitHub cannot reach it. To test provider setup locally, point `PASEO_HUB_APP_URL` at an HTTPS tunnel before starting Hub. A changed tunnel origin requires updated provider settings and a Hub restart.
## Upgrades
Pull the new image or source and deploy it. Migrations are forward-only. Back up PostgreSQL first; it contains configuration revisions, connections, and execution history.
public-docs/hub/self-hosting/slack-app.md
+1 -1
View File
@@ -8,7 +8,7 @@ category: Hub
# Slack for Hub
Hub receives Slack mentions over the Events API. Socket Mode is not used, so your Hub must be reachable from Slack.
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).
## Create the app