The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
fix: docker env overriding params (#397)
narrow-adventure05b6554633cd
diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.ymlindex 560ee552..2329ad36 100644--- a/.github/workflows/backend.yml+++ b/.github/workflows/backend.yml@@ -9,12 +9,14 @@ on:# imports cli/pkg/{client,mcpserver}, so a cli-only change can break the# backend build. cli.yml already lists backend/** for the same reason.- "cli/**"+ - "docker/start-backend.sh"- ".github/workflows/backend.yml"pull_request:types: [labeled]paths:- "backend/**"- "cli/**"+ - "docker/start-backend.sh"- ".github/workflows/backend.yml"workflow_dispatch:diff --git a/.plugin-scanner.toml b/.plugin-scanner.tomlindex 6e2173c0..159fbfa8 100644--- a/.plugin-scanner.toml+++ b/.plugin-scanner.toml@@ -3,7 +3,6 @@ ignore_paths = ["*_test.go","backend/app/repositories/transactional/pg/project.repository.go","backend/app/repositories/transactional/sqlite/project.repository.go",- "backend/cmd/run.go","backend/static/frontend/*","benchmarks/*","cli/internal/state/state.go",diff --git a/CLAUDE.md b/CLAUDE.mdindex 7ed04bc4..cd1fbf1b 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -39,11 +39,11 @@ Traceway is an error tracking and monitoring platform consisting of:**Node's version lives in `.nvmrc`** (a bare major, currently `26`) and nothing else derives it independently: every `setup-node` step uses `node-version-file: .nvmrc`, `flake.nix` reads it for the dev shells, and `release-traceway.yml` passes it to all five image builds as `--build-arg NODE_VERSION`. The Dockerfiles each carry an `ARG NODE_VERSION=<major>` default because a bare `docker build` cannot read `.nvmrc`; that default is the one value that can drift, which is what `scripts/check-node-pins.sh` exists to catch (it also fails on a literal `node:<major>` tag reintroduced in a `FROM`). To move Node, edit `.nvmrc` and the ARG defaults, then run the script. `frontend/package.json`'s `engines.node` is deliberately left as a floor (`>=22`) rather than a pin — it is what npm enforces on consumers, and `node-version-file` pointed at it resolves a range to the *newest* release, which is the drift `f95424cc` was fixing. `testing/devtesting-nestjs/Dockerfile` is out of scope: it pins the runtime of a sample third-party app, not anything Traceway builds.-Set `JWT_SECRET` (min 32 characters) before running the backend — it is the one variable with no default in the standalone binary (the all-in-one Docker image bakes a public one in via `backend/.env.docker`, which must be overridden in production). `SQLITE_PATH` sets the database location, defaulting to `./traceway.db` in the working directory.+Set `JWT_SECRET` (min 32 characters) before running the backend, including the All-in-One image. Former public signing keys are rejected. The All-in-One shell script leaves `.env` loading to the backend so Docker-provided values win. Embedded `Run(opts...)` never reads `JWT_SECRET`, since it runs inside the host app's process where that name usually belongs to the host: it takes `WithJWTSecret`, else `TRACEWAY_JWT_SECRET`, else a random key per start; set a stable secret to preserve dashboard sessions across embedded restarts. The All-in-One image's supervisord sends the backend's output to the container's stdout/stderr, so `docker logs` shows a startup rejection. `SQLITE_PATH` sets the database location, defaulting to `./traceway.db` in the working directory.CI on pull requests is opt-in. `backend.yml`, `backend-vulncheck.yml`, `cli.yml`, `cli-lint.yml`, `cli-contract.yml`, `frontend.yml` and `plugin-scanner.yml` listen for `pull_request: types: [labeled]` and every job is gated on `github.event.label.name == 'ci'`, so a PR runs nothing until a maintainer applies the `ci` label (only collaborators can), and applying any other label runs nothing either. Each application validates the PR as it is at that moment: to validate later pushes, remove and re-add the label. The same workflows still run on pushes to `main` that touch their paths (`backend/**`, `cli/**`, `frontend/**`, `skills/traceway/**` for `cli.yml`, `.nvmrc` for `frontend.yml`, their own workflow file; `plugin-scanner.yml` runs on every push to `main` because it scans the whole repo), on their daily schedules (the two vulnchecks), and from the Actions tab via `workflow_dispatch`.-Action versions are watched by `.github/dependabot.yml` (the `github-actions` ecosystem only; npm and Go modules are deliberately not watched there). It opens a weekly PR per group — `actions/*` in one, every third-party action in the other — and deliberately does **not** auto-apply `ci`, so a bot PR passes the same collaborator gate as any other. Label the first-party group to validate it; `golangci/golangci-lint-action` is reachable the same way via `cli-lint.yml`. The rest of the third-party group lands on `release-*.yml`, `benchmark-*.yml` and `traceway-autofix.yml`, which no label reaches — and `workflow_dispatch` is **not** a dry run on the release path: dispatching `release-docs.yml` or `release-website.yml` deploys to Cloudflare for real, and the other `release-*.yml` workflows publish real assets, so dispatching one from an unreviewed bot branch ships it. Validate those by reading the action's release notes instead, and dispatch only where the target is disposable. `traceway-autofix.yml` is the in-repo caller of the reusable `autofix.yml` (composite actions `.github/actions/autofix-prepare` and `autofix-publish` around the agent step; `docs/pages/learn/auto-fix.mdx` documents the contract); its `workflow_dispatch` takes an `issue_number` and runs the whole loop from the dispatched branch, which is the one pre-merge validation path for the `claude-code-action` pin — the most privileged action here — but it runs the agent for real, so dispatch it only at a scratch issue. Note too that labelling a PR which touches no gated workflow yields zero checks, which reads like a pass but is silence. Every updatable pin is a bare major tag, so Dependabot only ever proposes major bumps here. The exception is `plugin-scanner.yml`, which pins both actions to commit SHAs because the HOL scanner scores unpinned actions down; Dependabot bumps those SHAs along with their version comments. It uses the scanner config in `.plugin-scanner.toml`, whose `ignore_paths` cover fixtures, demos and build output plus four reviewed production files (the embedded-mode JWT default in `backend/cmd/run.go`, the read-only token mask in both `project.repository.go` copies, and `KindPassword` in `cli/internal/state/state.go`). The HOL registry's own scan ignores that file and still fails on syntax-highlighter strings in the committed `backend/static/frontend` bundle; that is accepted.+Action versions are watched by `.github/dependabot.yml` (the `github-actions` ecosystem only; npm and Go modules are deliberately not watched there). It opens a weekly PR per group — `actions/*` in one, every third-party action in the other — and deliberately does **not** auto-apply `ci`, so a bot PR passes the same collaborator gate as any other. Label the first-party group to validate it; `golangci/golangci-lint-action` is reachable the same way via `cli-lint.yml`. The rest of the third-party group lands on `release-*.yml`, `benchmark-*.yml` and `traceway-autofix.yml`, which no label reaches — and `workflow_dispatch` is **not** a dry run on the release path: dispatching `release-docs.yml` or `release-website.yml` deploys to Cloudflare for real, and the other `release-*.yml` workflows publish real assets, so dispatching one from an unreviewed bot branch ships it. Validate those by reading the action's release notes instead, and dispatch only where the target is disposable. `traceway-autofix.yml` is the in-repo caller of the reusable `autofix.yml` (composite actions `.github/actions/autofix-prepare` and `autofix-publish` around the agent step; `docs/pages/learn/auto-fix.mdx` documents the contract); its `workflow_dispatch` takes an `issue_number` and runs the whole loop from the dispatched branch, which is the one pre-merge validation path for the `claude-code-action` pin — the most privileged action here — but it runs the agent for real, so dispatch it only at a scratch issue. Note too that labelling a PR which touches no gated workflow yields zero checks, which reads like a pass but is silence. Every updatable pin is a bare major tag, so Dependabot only ever proposes major bumps here. The exception is `plugin-scanner.yml`, which pins both actions to commit SHAs because the HOL scanner scores unpinned actions down; Dependabot bumps those SHAs along with their version comments. It uses the scanner config in `.plugin-scanner.toml`, whose `ignore_paths` cover fixtures, demos and build output plus three reviewed production files (the read-only token mask in both `project.repository.go` copies and `KindPassword` in `cli/internal/state/state.go`). The HOL registry's own scan ignores that file and still fails on syntax-highlighter strings in the committed `backend/static/frontend` bundle; that is accepted.### Tech Stack- **Frontend**: SvelteKit 2.49, Svelte 5.45, Tailwind CSS v4, shadcn-svelte, Vite 7@@ -254,7 +254,7 @@ if err != nil {### Environment Variables (Backend)```-JWT_SECRET=<min 32 char secret for JWT signing> # the only variable with no default in the standalone binary. There is deliberately no fallback in the code: a key committed to the repo would be identical in every clone. The all-in-one Docker image is the exception, it copies `backend/.env.docker` with a public key that must be overridden in production. Unset or under 32 chars exits 1 with an actionable message rather than a panic.+JWT_SECRET=<min 32 char secret for JWT signing> # required in the standalone binary and every server image, including All-in-One. Missing, short and former public keys exit 1 with an actionable message. Docker's environment takes precedence over .env. Embedded Run(opts...) ignores JWT_SECRET (it belongs to the host app there): it uses WithJWTSecret, else TRACEWAY_JWT_SECRET (an explicitly empty value fails validation), else a random key per start, so set a stable value to preserve sessions across restarts. Retired public keys are matched by SHA-256 digest in jwt.service.go so no secret literal sits in scanned code.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_CACHE_SIZE_MB=512 # PRAGMA cache_size of the SQLite TELEMETRY DB in MB, per connection (the main DB keeps SQLite's 2MB default; no effect on DuckDB or ClickHouse telemetry). The telemetry pool opens up to 4 connections (`telemetryMaxOpenConns`, db_sqlite_open.go) and modernc's allocator rounds each ~4.4KB page buffer up to an 8KB slot, so resident memory is about 2x the value per connection: worst case 8x the value, 4GB at the default. A cache fills from ingest, from the retention DELETE scan at startup and every hour, and from reads of pages still in the WAL (write transactions and WAL pages bypass the 1GB mmap window), and it is held for as long as the pooled connection lives. At the default a 1GiB container is OOM-killed on a 24h dashboard or under sustained ingest (issue #396). Rule of thumb: container MB / 32 (16 for 512MB, 32 for 1GB, 64 for 2GB). A non-positive or unparsable value falls back to 512 (`config.SizeMB`). The effective value is logged at startup, and the embedded `Run(opts...)` path honors the env var through `applyEnvOverrides`. Operator docs: `docs/pages/server/sqlite.mdx#memory-sizing`.diff --git a/backend/.env.docker b/backend/.env.dockerindex 30476720..ad3b0537 100644--- a/backend/.env.docker+++ b/backend/.env.docker@@ -9,7 +9,6 @@ POSTGRES_DATABASE=tracewayPOSTGRES_USERNAME=tracewayPOSTGRES_PASSWORD=POSTGRES_SSLMODE=disable-JWT_SECRET=Xt7Kj2mP9qLwNc4rVb8sYd3hFgAeZuCpDnRoWxMvBa5kGIN_MODE=release# Optional retention knobs (defaults shown). Set to 0 to disable.diff --git a/backend/app/services/jwt.service.go b/backend/app/services/jwt.service.goindex 77c97560..00c55ac1 100644--- a/backend/app/services/jwt.service.go+++ b/backend/app/services/jwt.service.go@@ -1,16 +1,25 @@package servicesimport (+ "crypto/sha256"+ "encoding/hex""errors""fmt"- "github.com/tracewayapp/traceway/backend/app/config""time""github.com/golang-jwt/jwt/v5"+ "github.com/tracewayapp/traceway/backend/app/config")var jwtSecret []byte+// SHA-256 of signing keys that once shipped in the repo. Stored as digests so+// no secret-shaped literal sits in production code.+var retiredJWTSecretDigests = map[string]bool{+ "87710a3651ef56a2d43bfaafce1ee73dc8228c3c071788c8165bcf313e873127": true,+ "e7e45a50bcc0f78bf9cf470d4600937c1eeb0bda41d7eba67e3951a536f39221": true,+}+type JWTClaims struct {UserId int `json:"userId"`Email string `json:"email"`@@ -25,6 +34,10 @@ func InitJWT() error {if len(secret) < 32 {return errors.New("JWT_SECRET must be at least 32 characters")}+ digest := sha256.Sum256([]byte(secret))+ if retiredJWTSecretDigests[hex.EncodeToString(digest[:])] {+ return errors.New("JWT_SECRET uses a publicly known default; generate a unique secret")+ }jwtSecret = []byte(secret)return nil}diff --git a/backend/app/services/jwt.service_test.go b/backend/app/services/jwt.service_test.gonew file mode 100644index 00000000..d51ac167--- /dev/null+++ b/backend/app/services/jwt.service_test.go@@ -0,0 +1,83 @@+package services++import (+ "strings"+ "testing"+ "time"++ "github.com/golang-jwt/jwt/v5"+ "github.com/tracewayapp/traceway/backend/app/config"+)++func preserveJWTConfig(t *testing.T) {+ t.Helper()+ previousConfig, previousSecret := config.Config, jwtSecret+ t.Cleanup(func() {+ config.Config, jwtSecret = previousConfig, previousSecret+ })+}++func TestInitJWTRejectsUnsafeSecrets(t *testing.T) {+ preserveJWTConfig(t)+ for name, secret := range map[string]string{+ "missing": "",+ "short": strings.Repeat("s", 31),+ "all-in-one": "Xt7Kj2mP9qLwNc4rVb8sYd3hFgAeZuCpDnRoWxMvBa5k",+ "embedded": "traceway-dev-secret-key-min-32-chars!",+ } {+ t.Run(name, func(t *testing.T) {+ config.Config = &config.Cfg{JWTSecret: secret}+ if err := InitJWT(); err == nil {+ t.Fatal("accepted an unsafe signing key")+ }+ })+ }+}++func TestJWTUsesConfiguredSecretAndRejectsPublicKeyForgery(t *testing.T) {+ preserveJWTConfig(t)+ secret := strings.Repeat("private-test-key-", 4)+ config.Config = &config.Cfg{JWTSecret: secret}+ if err := InitJWT(); err != nil {+ t.Fatal(err)+ }+ claims := JWTClaims{+ UserId: 123,+ Email: "[email protected]",+ RegisteredClaims: jwt.RegisteredClaims{+ ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour)),+ },+ }+ for _, key := range []string{+ secret,+ "Xt7Kj2mP9qLwNc4rVb8sYd3hFgAeZuCpDnRoWxMvBa5k",+ "traceway-dev-secret-key-min-32-chars!",+ } {+ token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(key))+ if err != nil {+ t.Fatal(err)+ }+ got, err := ValidateToken(token)+ if key == secret {+ if err != nil || got.UserId != claims.UserId {+ t.Fatalf("configured key rejected: %v", err)+ }+ } else if err == nil {+ t.Fatal("accepted a token forged with a public key")+ }+ }+ issued, err := GenerateToken(claims.UserId, claims.Email)+ if err != nil {+ t.Fatal(err)+ }+ if _, err := jwt.Parse(issued, func(*jwt.Token) (any, error) { return []byte(secret), nil }); err != nil {+ t.Fatalf("issued token is not signed with the configured key: %v", err)+ }+ config.Config.JWTSecret = strings.Repeat("rotated-test-key-", 4)+ if err := InitJWT(); err != nil {+ t.Fatal(err)+ }+ if _, err := ValidateToken(issued); err == nil {+ t.Fatal("old token remained valid after key rotation")+ }+}diff --git a/backend/cmd/docker_startup_test.go b/backend/cmd/docker_startup_test.gonew file mode 100644index 00000000..dacde5ad--- /dev/null+++ b/backend/cmd/docker_startup_test.go@@ -0,0 +1,107 @@+package cmd++import (+ "fmt"+ "os"+ "os/exec"+ "path/filepath"+ "strings"+ "testing"++ "github.com/joho/godotenv"+ "github.com/tracewayapp/traceway/backend/app/config"+ "github.com/tracewayapp/traceway/backend/app/services"+)++func TestAllInOneStartupPreservesEnvironment(t *testing.T) {+ bash, err := exec.LookPath("bash")+ if err != nil {+ t.Skip("bash is required for the All-in-One entrypoint")+ }+ script, err := os.ReadFile("../../docker/start-backend.sh")+ if err != nil {+ t.Fatal(err)+ }+ defaults, err := os.ReadFile("../.env.docker")+ if err != nil {+ t.Fatal(err)+ }+ testBinary, err := os.Executable()+ if err != nil {+ t.Fatal(err)+ }+ const operatorSecret = "operator-test-key-with-$literal-characters"+ const oldSecret = "Xt7Kj2mP9qLwNc4rVb8sYd3hFgAeZuCpDnRoWxMvBa5k"+ for _, tc := range []struct {+ name string+ env []string+ fileSecret string+ wantSecret string+ wantError string+ }{+ {"operator overrides old file", []string{"JWT_SECRET=" + operatorSecret, "CLICKHOUSE_SERVER=external:9000", "POSTGRES_HOST=external"}, oldSecret, operatorSecret, ""},+ {"mounted file key", nil, operatorSecret, operatorSecret, ""},+ {"missing key", nil, "", "", "JWT_SECRET environment variable is not set"},+ {"explicit empty key", []string{"JWT_SECRET="}, operatorSecret, "", "JWT_SECRET environment variable is not set"},+ {"public environment key", []string{"JWT_SECRET=" + oldSecret}, "", "", "publicly known default"},+ {"old mounted file", nil, oldSecret, "", "publicly known default"},+ } {+ t.Run(tc.name, func(t *testing.T) {+ dir := t.TempDir()+ envFile := filepath.Join(dir, ".env")+ contents := string(defaults)+ if tc.fileSecret != "" {+ contents += "\nJWT_SECRET='" + tc.fileSecret + "'\n"+ }+ for name, content := range map[string]string{+ ".env": contents,+ "traceway": "#!/bin/sh\nexec \"$TRACEWAY_TEST_BINARY\" -test.run '^TestDockerBackendHelper$'\n",+ "wait-for-clickhouse.sh": "#!/bin/sh\nexit 0\n",+ "pg_isready": "#!/bin/sh\nexit 0\n",+ } {+ if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0700); err != nil {+ t.Fatal(err)+ }+ }+ // Map container paths to fixtures while executing the production script.+ entrypoint := strings.ReplaceAll(string(script), "/usr/local/bin/", dir+"/")+ entrypoint = strings.ReplaceAll(entrypoint, "/app/.env", envFile)+ command := exec.Command(bash, "-c", entrypoint)+ command.Dir = dir+ command.Env = append([]string{+ "PATH=" + dir + ":" + os.Getenv("PATH"),+ "TRACEWAY_TEST_BINARY=" + testBinary,+ "TRACEWAY_TEST_DOCKER_BACKEND=1",+ "TRACEWAY_TEST_WANT_SECRET=" + tc.wantSecret,+ }, tc.env...)+ output, err := command.CombinedOutput()+ if tc.wantError != "" {+ if err == nil || !strings.Contains(string(output), tc.wantError) {+ t.Fatalf("expected startup rejection %q: %v\n%s", tc.wantError, err, output)+ }+ } else if err != nil {+ t.Fatalf("startup failed: %v\n%s", err, output)+ }+ })+ }+}++func TestDockerBackendHelper(t *testing.T) {+ if os.Getenv("TRACEWAY_TEST_DOCKER_BACKEND") != "1" {+ return+ }+ if err := godotenv.Load(); err != nil {+ fmt.Fprintln(os.Stderr, err)+ os.Exit(1)+ }+ config.Init(config.LoadFromEnv())+ if err := services.InitJWT(); err != nil {+ fmt.Fprintln(os.Stderr, err)+ os.Exit(1)+ }+ if config.Config.JWTSecret != os.Getenv("TRACEWAY_TEST_WANT_SECRET") {+ fmt.Fprintln(os.Stderr, "startup replaced the configured signing key")+ os.Exit(1)+ }+ os.Exit(0)+}diff --git a/backend/cmd/options.go b/backend/cmd/options.goindex 5f0a763e..b7816976 100644--- a/backend/cmd/options.go+++ b/backend/cmd/options.go@@ -1,5 +1,29 @@package cmd+import (+ "crypto/rand"+ "encoding/hex"+ "log"+ "os"+)++// Embedded mode runs inside the host application's process, where JWT_SECRET+// usually belongs to the host app. Only Traceway-specific sources are read.+func embeddedJWTSecret(o *options) string {+ if o.jwtSecret != nil {+ return *o.jwtSecret+ }+ if secret, ok := os.LookupEnv("TRACEWAY_JWT_SECRET"); ok {+ return secret+ }+ if !o.disableLogging {+ log.Println("[tracewaybackend] No JWT secret configured, using a random one for this run. Dashboard sessions will not survive a restart. Pass tracewaybackend.WithJWTSecret(secret) (32+ characters) or set TRACEWAY_JWT_SECRET to keep them.")+ }+ secret := make([]byte, 32)+ rand.Read(secret)+ return hex.EncodeToString(secret)+}+type options struct {sqlitePath stringport int@@ -8,6 +32,7 @@ type options struct {defaultUser *defaultUserOptsdefaultProjects []defaultProjectOptsmonitoringTracewayURL string+ jwtSecret *string}type defaultUserOpts struct {@@ -77,3 +102,9 @@ func WithMonitoringURL(url string) Option {o.monitoringTracewayURL = url}}++func WithJWTSecret(secret string) Option {+ return func(o *options) {+ o.jwtSecret = &secret+ }+}diff --git a/backend/cmd/options_test.go b/backend/cmd/options_test.gonew file mode 100644index 00000000..41cfea36--- /dev/null+++ b/backend/cmd/options_test.go@@ -0,0 +1,55 @@+package cmd++import (+ "encoding/hex"+ "os"+ "strings"+ "testing"+)++func TestEmbeddedJWTSecretIgnoresHostJWTSecret(t *testing.T) {+ t.Setenv("JWT_SECRET", "host-app-key")+ t.Setenv("TRACEWAY_JWT_SECRET", "")+ if err := os.Unsetenv("TRACEWAY_JWT_SECRET"); err != nil {+ t.Fatal(err)+ }+ if got := embeddedJWTSecret(&options{}); got == "host-app-key" {+ t.Fatal("embedded mode adopted the host application's JWT_SECRET")+ }+}++func TestEmbeddedJWTSecretHonorsTracewayEnvironment(t *testing.T) {+ for _, secret := range []string{"", "short", strings.Repeat("operator-test-key-", 4)} {+ t.Setenv("TRACEWAY_JWT_SECRET", secret)+ if got := embeddedJWTSecret(&options{}); got != secret {+ t.Fatal("embedded mode replaced an explicitly configured TRACEWAY_JWT_SECRET")+ }+ }+}++func TestEmbeddedJWTSecretOptionWins(t *testing.T) {+ t.Setenv("TRACEWAY_JWT_SECRET", strings.Repeat("environment-key-", 4))+ o := &options{}+ want := strings.Repeat("option-test-key-", 4)+ WithJWTSecret(want)(o)+ if got := embeddedJWTSecret(o); got != want {+ t.Fatal("WithJWTSecret did not take precedence over the environment")+ }+}++func TestEmbeddedJWTSecretGeneratesIndependentKeys(t *testing.T) {+ t.Setenv("TRACEWAY_JWT_SECRET", "")+ if err := os.Unsetenv("TRACEWAY_JWT_SECRET"); err != nil {+ t.Fatal(err)+ }+ first, second := embeddedJWTSecret(&options{}), embeddedJWTSecret(&options{})+ if first == second {+ t.Fatal("embedded starts shared a signing key")+ }+ for _, secret := range []string{first, second} {+ decoded, err := hex.DecodeString(secret)+ if err != nil || len(decoded) != 32 {+ t.Fatalf("expected a 256-bit key, got %d bytes: %v", len(decoded), err)+ }+ }+}diff --git a/backend/cmd/run.go b/backend/cmd/run.goindex 20494fa0..3649b7d9 100644--- a/backend/cmd/run.go+++ b/backend/cmd/run.go@@ -62,7 +62,7 @@ func Run(opts ...Option) {port = 8082}cfg = &config.Cfg{- JWTSecret: "traceway-dev-secret-key-min-32-chars!",+ JWTSecret: embeddedJWTSecret(o),DBType: "sqlite",SQLitePath: o.sqlitePath,StorageType: "local",diff --git a/backend/traceway.go b/backend/traceway.goindex 981f5048..62fedebf 100644--- a/backend/traceway.go+++ b/backend/traceway.go@@ -12,6 +12,7 @@ var (WithDefaultUser = cmd.WithDefaultUserWithDefaultProject = cmd.WithDefaultProjectWithMonitoringURL = cmd.WithMonitoringURL+ WithJWTSecret = cmd.WithJWTSecretDisableLogging = cmd.DisableLoggingWithDefaultProjectSourceMapToken = cmd.WithDefaultProjectSourceMapTokendiff --git a/docker/start-backend.sh b/docker/start-backend.shindex 9acb42d3..adf614b0 100644--- a/docker/start-backend.sh+++ b/docker/start-backend.sh@@ -1,16 +1,17 @@#!/bin/bashset -e-set -a-source /app/.env-set +a+# The backend loads .env without overwriting Docker's environment. Sourcing it+# here would replace operator-provided secrets before the backend sees them.+clickhouse_server=${CLICKHOUSE_SERVER:-localhost:9000}+postgres_host=${POSTGRES_HOST:-localhost}-if [[ "$CLICKHOUSE_SERVER" == localhost* ]] || [[ "$CLICKHOUSE_SERVER" == 127.0.0.1* ]]; then+if [[ "$clickhouse_server" == localhost* ]] || [[ "$clickhouse_server" == 127.0.0.1* ]]; thenecho "Waiting for ClickHouse to be ready..."/usr/local/bin/wait-for-clickhouse.shfi-if [[ "$POSTGRES_HOST" == "localhost" ]] || [[ "$POSTGRES_HOST" == "127.0.0.1" ]]; then+if [[ "$postgres_host" == "localhost" ]] || [[ "$postgres_host" == "127.0.0.1" ]]; thenecho "Waiting for PostgreSQL to be ready..."MAX_RETRIES=30RETRY_INTERVAL=2diff --git a/docker/supervisord.conf b/docker/supervisord.confindex f6193e06..26f86142 100644--- a/docker/supervisord.conf+++ b/docker/supervisord.conf@@ -51,7 +51,7 @@ autorestart=truepriority=20startsecs=5startretries=3-stdout_logfile=/var/log/supervisor/backend-stdout.log-stderr_logfile=/var/log/supervisor/backend-stderr.log-stdout_logfile_maxbytes=10MB-stderr_logfile_maxbytes=10MB+stdout_logfile=/dev/stdout+stderr_logfile=/dev/stderr+stdout_logfile_maxbytes=0+stderr_logfile_maxbytes=0diff --git a/docs/pages/learn/cli-auth.mdx b/docs/pages/learn/cli-auth.mdxindex 312ebc50..19734a1c 100644--- a/docs/pages/learn/cli-auth.mdx+++ b/docs/pages/learn/cli-auth.mdx@@ -68,7 +68,7 @@ openssl rand -hex 32 # use the output as JWT_SECRET```- Minimum length is 32 characters; the server refuses to start with a shorter secret.-- The **All-in-One image ships a built-in default** so it can boot with zero config. That default is public, so override `JWT_SECRET` before you put the instance on a network anyone else can reach. Every other deployment guide already requires you to set it.+- **Every server image, including All-in-One, requires `JWT_SECRET`.** Former built-in keys are rejected. Older All-in-One images overwrote Docker-provided secrets; upgrade and recreate those containers with a unique key. See the [All-in-One upgrade note](/server/all-in-one#environment-variables).- Keep it **stable**. Rotating it logs out active dashboard sessions (users sign in again). CLI logins and personal access tokens are opaque, database-backed credentials, so those keep working: a CLI simply refreshes into a token signed with the new secret on its next call.`OAUTH_SESSION_SECRET` falls back to `JWT_SECRET` when unset; set it separately only if you want to rotate the OAuth cookie secret independently.diff --git a/docs/pages/learn/embedded-mode.mdx b/docs/pages/learn/embedded-mode.mdxindex 482f813f..2e3867ee 100644--- a/docs/pages/learn/embedded-mode.mdx+++ b/docs/pages/learn/embedded-mode.mdx@@ -238,6 +238,8 @@ On a laptop the defaults are fine. Inside a memory-capped dev container DuckDB sAll options are passed to `tracewaybackend.Run()`. When any options are provided, embedded mode is activated automatically.+Embedded mode signs dashboard sessions with the key from `WithJWTSecret`, else from the `TRACEWAY_JWT_SECRET` environment variable. It never reads `JWT_SECRET`, because that name usually belongs to your own application. With neither set, each start generates a random signing key and logs a line saying so, and dashboard sessions expire on restart. To keep sessions across restarts with a persistent database, pass a stable, unique secret of at least 32 characters. An empty, short, or former built-in secret stops startup and exits the process.+| Option | Description | Default || --------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------- || `WithPort(port)` | HTTP port for the Traceway server | `8082` |@@ -248,6 +250,7 @@ All options are passed to `tracewaybackend.Run()`. When any options are provided| `DisableLogging()` | Silence the embedded server's startup and request logs so they don't mix with your app's output | Logging enabled || `WithDefaultProjectSourceMapToken(name, token)` | Set a fixed source map upload token on a default project. Call it after the matching `WithDefaultProject`, since it looks the project up by name | None || `WithMonitoringURL(connectionString)` | Report the embedded server's own telemetry to another Traceway instance. Takes a connection string in the form `<project_token>@<url>/api/report` | None |+| `WithJWTSecret(secret)` | Signing key for dashboard sessions, at least 32 characters. Overrides `TRACEWAY_JWT_SECRET` | Random key per start |If the embedded server's startup lines get in the way of your own output, add `tracewaybackend.DisableLogging()` to the option list:diff --git a/docs/pages/server/all-in-one.mdx b/docs/pages/server/all-in-one.mdxindex 3a424872..53869205 100644--- a/docs/pages/server/all-in-one.mdx+++ b/docs/pages/server/all-in-one.mdx@@ -10,12 +10,20 @@ Single Docker container with ClickHouse, PostgreSQL, and the Go backend managed## Quick Start-Pull the pre-built image from GitHub Container Registry:+Generate a signing secret once and save it in a private environment file. Keep this file out of source control and reuse it when recreating the container:++```bash+umask 077+printf 'JWT_SECRET=%s\n' "$(openssl rand -hex 32)" > traceway.env+```++Pull the pre-built image from GitHub Container Registry and pass that file to Docker:```bashdocker pull ghcr.io/tracewayapp/traceway:latestdocker run -d --name traceway \+ --env-file ./traceway.env \-p 80:80 \-v traceway-ch:/var/lib/clickhouse \-v traceway-pg:/var/lib/postgresql/data \@@ -29,12 +37,13 @@ The `traceway-storage` volume holds [blob storage](/server/storage): uploaded so## Build from Source-Only needed if you want to run a custom or modified build:+Only needed if you want to run a custom or modified build. Create `traceway.env` as shown above first:```bashdocker build -t traceway:latest .docker run -d --name traceway \+ --env-file ./traceway.env \-p 80:80 \-v traceway-ch:/var/lib/clickhouse \-v traceway-pg:/var/lib/postgresql/data \@@ -44,10 +53,10 @@ docker run -d --name traceway \## Environment Variables-All environment variables have working defaults, no configuration required. Override as needed:+`JWT_SECRET` is required. The other variables below have defaults. Docker environment values (`-e` or `--env-file`) take precedence over values in `/app/.env`.<Callout type="warning">- **Set `JWT_SECRET` before exposing this image to anyone else.** It signs every authentication token (dashboard sessions and CLI/MCP device logins), so the built-in default, which is public, lets anyone forge a token for any account. Generate a strong secret with `openssl rand -hex 32`. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret).+ **Upgrading an existing All-in-One installation:** older images replaced Docker-provided `JWT_SECRET` values with a public signing key. Upgrade the image and recreate the container with a strong, unique secret. The backend now refuses to start with a missing, short, or former built-in key, and `docker logs traceway` shows why. Changing the effective key invalidates existing JWTs. If the old instance was accessible to untrusted users, review access logs, account changes, personal access tokens and CLI/OAuth sessions; database-backed credentials survive JWT key rotation. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret).</Callout>| Variable | Default | Description |@@ -63,7 +72,7 @@ All environment variables have working defaults, no configuration required. Over| `POSTGRES_USERNAME` | `traceway` | PostgreSQL username || `POSTGRES_PASSWORD` | *(empty)* | PostgreSQL password || `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). |+| `JWT_SECRET` | *(required)* | Signs dashboard sessions and CLI/MCP access tokens. Set a strong unique secret (min 32 chars, `openssl rand -hex 32`) and keep it stable. Former built-in keys are rejected. 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, 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. |