Skip to content

The only tool you need to know what is happening and how to fix it.

notifications: absolute deep links when APP_BASE_URL is set (#355)

FrameAutomatae441b86e9bbc
diff --git a/CLAUDE.md b/CLAUDE.md
index 500ff152..180b37c4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -258,7 +258,7 @@ JWT_SECRET=<min 32 char secret for JWT signing> # the only variable with no de
DB_TYPE= # sqlite | postgres. Defaults to sqlite in every build EXCEPT -tags transactional_pg, where an empty value still selects PostgreSQL. Without that tag SQLite is the only supported main DB (the migration runner applies SQLite-dialect migrations unconditionally), so the default is set once in config.defaultDBType rather than at each DBType call site.
PORTS=80,8082 # comma-separated HTTP listen ports. Every port is bound up front; a port that fails to bind (typically :80 as a non-root user) logs a warning (and reports via CaptureException when monitoring is configured), and startup only fails if NO port binds. Order is not significant: a listener that later stops serving takes the process down whichever position it holds.
SQLITE_PATH= # main DB path, defaults to ./traceway.db in the working directory. The telemetry DB derives from it (_telemetry.db, or _telemetry.duckdb under -tags telemetry_duckdb).
-APP_BASE_URL= # public origin of this server (e.g. https://traceway.example.com). Used as the OAuth issuer / device verification URL and SSO redirect base. If unset, the device-auth + well-known endpoints derive it per-request from the Host / X-Forwarded-* headers; set it explicitly behind a proxy that doesn't forward Host.
+APP_BASE_URL= # public origin of this server (e.g. https://traceway.example.com). Used as the OAuth issuer / device verification URL and SSO redirect base, and to absolutize the deep links in notifications. If unset, the device-auth + well-known endpoints derive it per-request from the Host / X-Forwarded-* headers; set it explicitly behind a proxy that doesn't forward Host.
TRUSTED_PROXIES= # comma-separated IPs/CIDRs whose X-Forwarded-For/X-Real-IP gin trusts for c.ClientIP() (every per-IP rate limiter keys on it, and `/api/report` stores it on every session as `client.ip`). Unset = loopback only, so no peer can spoof its IP. Private ranges are deliberately NOT trusted by default: on a Docker/k8s network every peer has a private address, the clients included when the port is published directly, so trusting RFC1918 would let any of them forge XFF past every per-IP limiter. Set it to the CIDRs of whatever sits in front (a proxy container's compose network, the ingress pod range, the CDN ranges); otherwise every visitor shares one rate-limit bucket keyed on the proxy. The value REPLACES the default, so it must name every hop in the chain, not just the outermost (a CDN-only list leaves a private ingress untrusted and disables XFF entirely); `*` trusts every peer. A malformed entry exits 1 at startup with a FATAL message, before the database is opened (`trustedProxyNets`, cmd/run.go). The first request carrying X-Forwarded-For/X-Real-IP from a peer outside the list logs a one-time warning naming that peer (`warnOnUntrustedForwardedFor`, cmd/run.go), which is how a forgotten proxy hop shows up. Parsing lives in `Cfg.TrustedProxyList` (config.go), covered by config_test.go.
TRUSTED_PROXY_HEADER= # optional header taken verbatim as the client IP on every request (gin TrustedPlatform: X-Real-IP behind ingress-nginx, CF-Connecting-IP behind Cloudflare); it wins over TRUSTED_PROXIES and turns the untrusted-forwarder warning off. Only safe when every request provably passes through a proxy that overwrites the header.
UPLOAD_MAX_CONCURRENT=4 # concurrent /api/sourcemaps/upload + /api/symbols/upload requests; excess waits 30s then gets 503. Separate from INGEST_MAX_CONCURRENT so a CI upload burst cannot starve telemetry ingest. Each upload holds a whole file in memory while parsing, so this bounds peak upload memory at roughly concurrency x largest file. It is a count-based gate, not a memory budget: on a memory-capped container size it from the limit rather than trusting the default. Same gate and bounded waiting room as ingest, its own instance. The source-map warm-up that follows an upload (`services.GenerateTWArtifacts`) runs outside this gate on its own 2-worker pool with a 64-job queue: the stale `.tw` artifact is deleted and the cache invalidated inline, the rebuild is queued, identical pending jobs are coalesced, and a full queue drops the warm-up (rate-limited `CaptureException`) because lookups build a missing artifact on demand anyway.
diff --git a/backend/app/config/config.go b/backend/app/config/config.go
index 2734cb51..9dfefdb1 100644
--- a/backend/app/config/config.go
+++ b/backend/app/config/config.go
@@ -178,6 +178,29 @@ func (c *Cfg) TwilioEnabled() bool {
(c.TwilioFromNumber != "" || c.TwilioMessagingServiceSID != "")
}
+// devBaseURL is the origin assumed when APP_BASE_URL is unset. Links that
+// must be clickable regardless (emails, on-call pages) fall back to it; the
+// Vite dev server is where a dashboard without a configured origin lives.
+const devBaseURL = "http://localhost:5173"
+
+// PublicBaseURL is the dashboard origin (APP_BASE_URL without surrounding
+// whitespace or a trailing slash), or empty when the operator has not set one.
+func (c *Cfg) PublicBaseURL() string {
+ if c == nil {
+ return ""
+ }
+ return strings.TrimRight(strings.TrimSpace(c.AppBaseURL), "/")
+}
+
+// PublicBaseURLOrDev is PublicBaseURL for callers that need some origin to
+// build a link with, even on an instance that never configured one.
+func (c *Cfg) PublicBaseURLOrDev() string {
+ if base := c.PublicBaseURL(); base != "" {
+ return base
+ }
+ return devBaseURL
+}
+
func LoadFromEnv() *Cfg {
return &Cfg{
JWTSecret: os.Getenv("JWT_SECRET"),
diff --git a/backend/app/notifications/dispatch.go b/backend/app/notifications/dispatch.go
index 09d43436..cc875def 100644
--- a/backend/app/notifications/dispatch.go
+++ b/backend/app/notifications/dispatch.go
@@ -45,6 +45,7 @@ func dispatch(rule *models.NotificationRuleWithChannel, msg Message) bool {
if rule.Severity != "" {
msg.Severity = Severity(rule.Severity)
}
+ msg.URL = dashboardURL(msg.URL)
// Escalation channels do not send anything themselves: they open (or
// dedup into) an on-call page, and the escalator + outbox do all
diff --git a/backend/app/notifications/dispatch_outbox_test.go b/backend/app/notifications/dispatch_outbox_test.go
index f58306d2..37954f03 100644
--- a/backend/app/notifications/dispatch_outbox_test.go
+++ b/backend/app/notifications/dispatch_outbox_test.go
@@ -4,9 +4,12 @@ package notifications
import (
"database/sql"
+ "encoding/json"
+ "strings"
"testing"
"time"
+ "github.com/tracewayapp/traceway/backend/app/config"
"github.com/tracewayapp/traceway/backend/app/db"
"github.com/tracewayapp/traceway/backend/app/dbtest"
"github.com/tracewayapp/traceway/backend/app/models"
@@ -150,3 +153,55 @@ func TestSeedCooldownsIncludesOutbox(t *testing.T) {
t.Error("outbox-backed seeding should keep the rule in cooldown after restart")
}
}
+
+func setAppBaseURL(t *testing.T, base string) {
+ t.Helper()
+ previous := config.Config.AppBaseURL
+ config.Config.AppBaseURL = base
+ t.Cleanup(func() { config.Config.AppBaseURL = previous })
+}
+
+func queuedMessage(t *testing.T) Message {
+ t.Helper()
+ rows := outboxRows(t)
+ if len(rows) != 1 {
+ t.Fatalf("expected 1 outbox row, got %d", len(rows))
+ }
+ var msg Message
+ if err := json.Unmarshal(rows[0].Message, &msg); err != nil {
+ t.Fatalf("decode queued message: %v", err)
+ }
+ return msg
+}
+
+// The link reaches an adapter two ways — the URL field, which webhook,
+// telegram, pushover and sms render, and the "View details" body line, which
+// is the only one Slack and GitHub ever show — so both are asserted.
+func TestDispatchDashboardLinks(t *testing.T) {
+ cases := []struct {
+ name string
+ base string
+ want string
+ }{
+ {"absolute when APP_BASE_URL is set", "https://traceway.example.com/", "https://traceway.example.com/issues/0123456789abcdef"},
+ {"relative when it is not", "", "/issues/0123456789abcdef"},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ fixture := setupDispatchDB(t)
+ setAppBaseURL(t, tc.base)
+
+ details := ExceptionDetails{Hash: "0123456789abcdef", ErrorType: "RuntimeError"}
+ if !dispatch(fixture.Rule, buildNewErrorMessage(details, "api")) {
+ t.Fatal("dispatch failed")
+ }
+ msg := queuedMessage(t)
+ if msg.URL != tc.want {
+ t.Errorf("URL = %q, want %q", msg.URL, tc.want)
+ }
+ if !strings.Contains(msg.Body, "View details: "+tc.want) {
+ t.Errorf("body lacks %q:\n%s", tc.want, msg.Body)
+ }
+ })
+ }
+}
diff --git a/backend/app/notifications/messages.go b/backend/app/notifications/messages.go
index 68b84976..e703398a 100644
--- a/backend/app/notifications/messages.go
+++ b/backend/app/notifications/messages.go
@@ -6,9 +6,22 @@ import (
"strings"
"time"
+ "github.com/tracewayapp/traceway/backend/app/config"
"github.com/tracewayapp/traceway/backend/app/models"
)
+// dashboardURL makes a dashboard path absolute when APP_BASE_URL is set.
+// Without it the path stays relative: a guessed localhost origin would be
+// wrong for everyone reading a Slack post or a GitHub issue, whereas the bare
+// path still identifies the page.
+func dashboardURL(path string) string {
+ base := config.Config.PublicBaseURL()
+ if base == "" || !strings.HasPrefix(path, "/") {
+ return path
+ }
+ return base + path
+}
+
func alertEmail(alert models.EmailAlert) *models.NotificationEmail {
return &models.NotificationEmail{Template: models.EmailTemplateAlert, Alert: &alert}
}
@@ -476,7 +489,7 @@ func buildExceptionBody(headline string, d ExceptionDetails) string {
}
if d.Hash != "" {
- fmt.Fprintf(&b, "\n\nView details: /issues/%s", d.Hash)
+ fmt.Fprintf(&b, "\n\nView details: %s", dashboardURL("/issues/"+d.Hash))
}
return b.String()
diff --git a/backend/app/oncall/escalator.go b/backend/app/oncall/escalator.go
index 068c9050..f226e9c7 100644
--- a/backend/app/oncall/escalator.go
+++ b/backend/app/oncall/escalator.go
@@ -578,14 +578,8 @@ func newAckToken() string {
}
// appBaseURL is the dashboard origin for outgoing links. On-call deployments
-// should set APP_BASE_URL; the localhost fallback mirrors the email service.
-func appBaseURL() string {
- base := config.Config.AppBaseURL
- if base == "" {
- base = "http://localhost:5173"
- }
- return strings.TrimRight(base, "/")
-}
+// should set APP_BASE_URL; without it an ack link still has to be clickable.
+func appBaseURL() string { return config.Config.PublicBaseURLOrDev() }
// ackURLFor builds the public no-login acknowledge link for a delivery token.
func ackURLFor(token string) string {
diff --git a/backend/app/services/email.service.go b/backend/app/services/email.service.go
index da9a4c30..a91d191f 100644
--- a/backend/app/services/email.service.go
+++ b/backend/app/services/email.service.go
@@ -67,12 +67,7 @@ func (e *emailService) BaseURL() string { return emailBaseURL() }
func emailEnabled() bool { return config.Config != nil && config.Config.SMTPEnabled == "true" }
-func emailBaseURL() string {
- if config.Config != nil && config.Config.AppBaseURL != "" {
- return strings.TrimRight(config.Config.AppBaseURL, "/")
- }
- return "http://localhost:5173"
-}
+func emailBaseURL() string { return config.Config.PublicBaseURLOrDev() }
func RenderEmail(email Email) (string, error) {
if email.LogoURL == "" {
diff --git a/cli/pkg/mcpserver/knowledge/notifications.md b/cli/pkg/mcpserver/knowledge/notifications.md
index 322bbb19..049bdc6e 100644
--- a/cli/pkg/mcpserver/knowledge/notifications.md
+++ b/cli/pkg/mcpserver/knowledge/notifications.md
@@ -9,7 +9,7 @@ The body embeds everything for a direct, fast lookup. It contains:
- `Hash: <16-hex>` — the exception group → `traceway exceptions show <hash>`.
- `Exception ID: <uuid>` — the specific occurrence.
- `Occurred at: 2006-01-02 15:04:05 UTC` — the occurrence timestamp. **Convert to RFC3339**: replace the space with `T` and ` UTC` with `Z` (→ `2006-01-02T15:04:05Z`).
-- `View details: /issues/<hash>` — the deep link.
+- `View details: <url>` — the deep link, `https://<instance>/issues/<hash>` when the server sets `APP_BASE_URL`, otherwise the bare path `/issues/<hash>`.
So from a notification, go straight to the occurrence (fast), then pivot reusing the same timestamp:
diff --git a/docs/pages/learn/alerts.mdx b/docs/pages/learn/alerts.mdx
index 02f0831d..c37ae5c5 100644
--- a/docs/pages/learn/alerts.mdx
+++ b/docs/pages/learn/alerts.mdx
@@ -104,7 +104,7 @@ When a webhook channel fires, Traceway sends a JSON POST request with the follow
| `severity` | `info`, `warning`, or `critical` |
| `ruleType` | The rule type that triggered the alert |
| `ruleName` | The name you gave the rule |
-| `url` | Deep link to the relevant dashboard page |
+| `url` | Deep link to the relevant dashboard page. Absolute when the server sets `APP_BASE_URL`, otherwise a path such as `/issues/<hash>` relative to your dashboard origin |
| `timestamp` | When the alert fired (ISO 8601) |
If you configure an HMAC secret on the channel, each request includes an `X-Traceway-Signature` header containing `sha256=<hex>` of the request body, which you can use to verify that the request came from Traceway.
diff --git a/docs/pages/server/all-in-one.mdx b/docs/pages/server/all-in-one.mdx
index b1d907a2..3a424872 100644
--- a/docs/pages/server/all-in-one.mdx
+++ b/docs/pages/server/all-in-one.mdx
@@ -65,7 +65,7 @@ All environment variables have working defaults, no configuration required. Over
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode |
| `JWT_SECRET` | *(built-in default, **override in production**)* | Signs all authentication tokens: dashboard sessions and CLI/MCP device logins. The built-in default is public; set a strong unique secret (min 32 chars, `openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). |
| `GIN_MODE` | `release` | Gin framework mode |
-| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |
+| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, deep links in notifications, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |
| `TRUSTED_PROXIES` | *(loopback)* | Comma-separated CIDRs of the proxies in front of Traceway whose `X-Forwarded-For` / `X-Real-IP` is trusted for the real client IP. Every per-IP rate limit keys on it, and `/api/report` stores it as each session's `client.ip`. Unset trusts loopback only, so a proxy container on a Docker network or an in-cluster ingress has to be listed before its header counts. A value replaces the default, so list every hop between the client and this server, not just the outermost one: naming only a CDN leaves a private ingress untrusted and turns `X-Forwarded-For` off entirely. `*` trusts every peer and lets clients spoof their address. Until the proxy is listed, every visitor shares one rate-limit bucket keyed on the proxy, and the server logs a warning the first time it sees a forwarding header from a peer it does not trust. |
| `TRUSTED_PROXY_HEADER` | *(none)* | A header taken as the client IP on every request, ahead of `TRUSTED_PROXIES`: `X-Real-IP` behind ingress-nginx, `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. |
| `REPORT_MAX_BODY_MB` | `64` | Cap on the decompressed `/api/report` and `/api/profiles/ingest` body in megabytes. Gzip does not raise it. A body over the cap answers `413`. |
diff --git a/docs/pages/server/docker-compose.mdx b/docs/pages/server/docker-compose.mdx
index 23f05a8f..22588cc9 100644
--- a/docs/pages/server/docker-compose.mdx
+++ b/docs/pages/server/docker-compose.mdx
@@ -99,7 +99,7 @@ Edit the environment variables in your compose file as needed:
| `POSTGRES_PASSWORD` | `traceway` | PostgreSQL password |
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode |
| `JWT_SECRET` | `change-this-to-a-secure-secret-at-least-32-chars` | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Replace the placeholder with a strong, unique secret of at least 32 chars (`openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). |
-| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |
+| `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, deep links in notifications, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |
| `TRUSTED_PROXIES` | *(loopback)* | Comma-separated CIDRs of the proxies in front of Traceway whose `X-Forwarded-For` / `X-Real-IP` is trusted for the real client IP. Every per-IP rate limit keys on it, and `/api/report` stores it as each session's `client.ip`. Unset trusts loopback only, so a proxy container on a Docker network or an in-cluster ingress has to be listed before its header counts. A value replaces the default, so list every hop between the client and this server, not just the outermost one: naming only a CDN leaves a private ingress untrusted and turns `X-Forwarded-For` off entirely. `*` trusts every peer and lets clients spoof their address. Until the proxy is listed, every visitor shares one rate-limit bucket keyed on the proxy, and the server logs a warning the first time it sees a forwarding header from a peer it does not trust. |
| `TRUSTED_PROXY_HEADER` | *(none)* | A header taken as the client IP on every request, ahead of `TRUSTED_PROXIES`: `X-Real-IP` behind ingress-nginx, `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. |
| `REPORT_MAX_BODY_MB` | `64` | Cap on the decompressed `/api/report` and `/api/profiles/ingest` body in megabytes. Gzip does not raise it. A body over the cap answers `413`. |
diff --git a/docs/pages/server/haloy.mdx b/docs/pages/server/haloy.mdx
index f19d464d..a27d885e 100644
--- a/docs/pages/server/haloy.mdx
+++ b/docs/pages/server/haloy.mdx
@@ -163,7 +163,7 @@ Point your SDK's connection string at your Traceway domain:
| Variable | Default | Description |
|----------|---------|-------------|
-| `APP_BASE_URL` | `https://traceway.yourdomain.com` | Public URL of the Traceway instance. Also the CLI/MCP OAuth issuer and device-login verification URL. See [CLI Authentication](/learn/cli-auth). |
+| `APP_BASE_URL` | `https://traceway.yourdomain.com` | Public URL of the Traceway instance. Also what the deep links in notifications are built from, and the CLI/MCP OAuth issuer and device-login verification URL. See [CLI Authentication](/learn/cli-auth). |
| `TRUSTED_PROXIES` | *(loopback)* | Comma-separated CIDRs of the proxies in front of Traceway whose `X-Forwarded-For` / `X-Real-IP` is trusted for the real client IP. Every per-IP rate limit keys on it, and `/api/report` stores it as each session's `client.ip`. Unset trusts loopback only, so a proxy container on a Docker network or an in-cluster ingress has to be listed before its header counts. A value replaces the default, so list every hop between the client and this server, not just the outermost one: naming only a CDN leaves a private ingress untrusted and turns `X-Forwarded-For` off entirely. `*` trusts every peer and lets clients spoof their address. Until the proxy is listed, every visitor shares one rate-limit bucket keyed on the proxy, and the server logs a warning the first time it sees a forwarding header from a peer it does not trust. Haloy fronts the app with its own proxy, so list the range that proxy connects from (and your CDN's, if any). |
| `TRUSTED_PROXY_HEADER` | *(none)* | A header taken as the client IP on every request, ahead of `TRUSTED_PROXIES`: `X-Real-IP` behind ingress-nginx, `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. |
| `REPORT_MAX_BODY_MB` | `64` | Cap on the decompressed `/api/report` and `/api/profiles/ingest` body in megabytes. Gzip does not raise it. A body over the cap answers `413`. |
diff --git a/docs/pages/server/local-setup.mdx b/docs/pages/server/local-setup.mdx
index efd7bba6..0d8831b8 100644
--- a/docs/pages/server/local-setup.mdx
+++ b/docs/pages/server/local-setup.mdx
@@ -73,7 +73,7 @@ POSTGRES_SSLMODE=disable
| `POSTGRES_USERNAME` | PostgreSQL username |
| `POSTGRES_PASSWORD` | PostgreSQL password |
| `POSTGRES_SSLMODE` | PostgreSQL SSL mode (`disable`, `require`, etc.) |
-| `APP_BASE_URL` | Public URL of your Traceway instance. Used for SDK connection instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. For local dev set this to `http://localhost:5173` so OAuth callbacks land on the Vite dev server (which proxies `/api` back to the Go backend). |
+| `APP_BASE_URL` | Public URL of your Traceway instance. Used for SDK connection instructions, email links, deep links in notifications, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. For local dev set this to `http://localhost:5173` so OAuth callbacks land on the Vite dev server (which proxies `/api` back to the Go backend). |
| `GOOGLE_CLIENT_ID` | Optional. Google OAuth client ID. Setting both Google variables enables the **Continue with Google** button. See the [SSO guide](/learn/sso). |
| `GOOGLE_CLIENT_SECRET` | Optional. Google OAuth client secret. |
| `GITHUB_CLIENT_ID` | Optional. GitHub OAuth App client ID. Setting both GitHub variables enables the **Continue with GitHub** button. See the [SSO guide](/learn/sso). |
diff --git a/docs/pages/server/minimal.mdx b/docs/pages/server/minimal.mdx
index 04b7472b..9059a434 100644
--- a/docs/pages/server/minimal.mdx
+++ b/docs/pages/server/minimal.mdx
@@ -57,7 +57,7 @@ Then use `traceway:minimal` instead of `ghcr.io/tracewayapp/traceway:minimal` in
| `POSTGRES_PASSWORD` | PostgreSQL password | `password` |
| `POSTGRES_SSLMODE` | PostgreSQL SSL mode | `disable` |
| `JWT_SECRET` | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Use a strong, unique secret of at least 32 chars; keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). | `your-secret-here` |
-| `APP_BASE_URL` | Public URL of your instance. Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, derived per-request from `Host` / `X-Forwarded-*`. | `https://traceway.example.com` |
+| `APP_BASE_URL` | Public URL of your instance. Used for SDK setup instructions, email links, deep links in notifications, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, derived per-request from `Host` / `X-Forwarded-*`. | `https://traceway.example.com` |
| `TRUSTED_PROXIES` | Comma-separated CIDRs of the proxies in front of Traceway whose `X-Forwarded-For` / `X-Real-IP` is trusted for the real client IP. Every per-IP rate limit keys on it, and `/api/report` stores it as each session's `client.ip`. Unset trusts loopback only, so a proxy container on a Docker network or an in-cluster ingress has to be listed before its header counts. A value replaces the default, so list every hop between the client and this server, not just the outermost one: naming only a CDN leaves a private ingress untrusted and turns `X-Forwarded-For` off entirely. `*` trusts every peer and lets clients spoof their address. Until the proxy is listed, every visitor shares one rate-limit bucket keyed on the proxy, and the server logs a warning the first time it sees a forwarding header from a peer it does not trust. | `10.0.0.0/8,192.168.0.0/16` |
| `TRUSTED_PROXY_HEADER` | A header taken as the client IP on every request, ahead of `TRUSTED_PROXIES`: `X-Real-IP` behind ingress-nginx, `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. | `X-Real-IP` |
| `REPORT_MAX_BODY_MB` | Cap on the decompressed `/api/report` and `/api/profiles/ingest` body in megabytes. Gzip does not raise it. A body over the cap answers `413`. | `64` |
diff --git a/docs/pages/server/sqlite.mdx b/docs/pages/server/sqlite.mdx
index 6bab04ec..b7da7d3e 100644
--- a/docs/pages/server/sqlite.mdx
+++ b/docs/pages/server/sqlite.mdx
@@ -67,7 +67,7 @@ If `STORAGE_TYPE` is unset (or set to `local`), blobs are written to `/data/stor
| Variable | Default | Description |
|----------|---------|-------------|
| `JWT_SECRET` | *(required)* | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Use a strong, unique secret of at least 32 characters (`openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). |
-| `APP_BASE_URL` | *(unset)* | Public URL of your instance. Used for SDK setup snippets, password-reset emails, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers. See [CLI Authentication](/learn/cli-auth) |
+| `APP_BASE_URL` | *(unset)* | Public URL of your instance. Used for SDK setup snippets, password-reset emails, OAuth callback URLs, deep links in notifications, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers. See [CLI Authentication](/learn/cli-auth) |
| `TRUSTED_PROXIES` | *(loopback)* | Comma-separated CIDRs of the proxies in front of Traceway whose `X-Forwarded-For` / `X-Real-IP` is trusted for the real client IP. Every per-IP rate limit keys on it, and `/api/report` stores it as each session's `client.ip`. Unset trusts loopback only, so a proxy container on a Docker network or an in-cluster ingress has to be listed before its header counts. A value replaces the default, so list every hop between the client and this server, not just the outermost one: naming only a CDN leaves a private ingress untrusted and turns `X-Forwarded-For` off entirely. `*` trusts every peer and lets clients spoof their address. Until the proxy is listed, every visitor shares one rate-limit bucket keyed on the proxy, and the server logs a warning the first time it sees a forwarding header from a peer it does not trust. |
| `TRUSTED_PROXY_HEADER` | *(none)* | A header taken as the client IP on every request, ahead of `TRUSTED_PROXIES`: `X-Real-IP` behind ingress-nginx, `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. |
| `REPORT_MAX_BODY_MB` | `64` | Cap on the decompressed `/api/report` and `/api/profiles/ingest` body in megabytes. Gzip does not raise it. A body over the cap answers `413`. |
@@ -166,7 +166,7 @@ docker stop traceway && docker rm traceway
|----------|-------|-------|
| `JWT_SECRET` | a random string ≥ 32 chars | Required. Generate with `openssl rand -hex 32` |
| `PORTS` | `${{PORT}}` | Railway exposes a single port via `PORT`. The app's `PORTS` setting accepts a single value, so this binds the server where Railway expects it |
-| `APP_BASE_URL` | `https://<your-service>.up.railway.app` | Optional but recommended once you generate a domain. Makes SDK snippets and reset emails point at the right URL |
+| `APP_BASE_URL` | `https://<your-service>.up.railway.app` | Optional but recommended once you generate a domain. Makes SDK snippets, reset emails and the deep links in notifications point at the right URL |
To use external object storage, also set `STORAGE_TYPE=s3`, `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, and optionally `S3_ENDPOINT`. Otherwise blobs are written to `/data/storage` on the volume you added above.
diff --git a/skills/traceway/SKILL.md b/skills/traceway/SKILL.md
index 7dfeae19..ca0eaae3 100644
--- a/skills/traceway/SKILL.md
+++ b/skills/traceway/SKILL.md
@@ -86,7 +86,7 @@ The body embeds everything for a direct, fast lookup. It contains:
- `Hash: <16-hex>` — the exception group → `traceway exceptions show <hash>`.
- `Exception ID: <uuid>` — the specific occurrence.
- `Occurred at: 2006-01-02 15:04:05 UTC` — the occurrence timestamp. **Convert to RFC3339**: replace the space with `T` and ` UTC` with `Z` (→ `2006-01-02T15:04:05Z`).
-- `View details: /issues/<hash>` — the deep link.
+- `View details: <url>` — the deep link, `https://<instance>/issues/<hash>` when the server sets `APP_BASE_URL`, otherwise the bare path `/issues/<hash>`.
So from a notification, go straight to the occurrence (fast), then pivot reusing the same timestamp: