From eba1467366d2af59cf5a8703b9902f556763e7cf Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Wed, 28 Oct 2026 14:48:23 +0100 Subject: [PATCH 01/13] feat(docs): first draft --- docs/antora.yml | 7 + docs/modules/ROOT/nav.adoc | 13 + docs/modules/ROOT/pages/getting-started.adoc | 51 ++++ docs/modules/ROOT/pages/index.adoc | 26 ++ .../pages/installation/authentication.adoc | 30 +++ .../ROOT/pages/installation/database.adoc | 23 ++ .../modules/ROOT/pages/installation/helm.adoc | 68 +++++ .../ROOT/pages/installation/monitoring.adoc | 10 + .../modules/ROOT/pages/modules/bookmarks.adoc | 30 +++ docs/modules/ROOT/pages/modules/storage.adoc | 54 ++++ docs/modules/ROOT/pages/modules/trino.adoc | 45 ++++ .../reference/environment-variables.adoc | 243 ++++++++++++++++++ 12 files changed, 600 insertions(+) create mode 100644 docs/antora.yml create mode 100644 docs/modules/ROOT/nav.adoc create mode 100644 docs/modules/ROOT/pages/getting-started.adoc create mode 100644 docs/modules/ROOT/pages/index.adoc create mode 100644 docs/modules/ROOT/pages/installation/authentication.adoc create mode 100644 docs/modules/ROOT/pages/installation/database.adoc create mode 100644 docs/modules/ROOT/pages/installation/helm.adoc create mode 100644 docs/modules/ROOT/pages/installation/monitoring.adoc create mode 100644 docs/modules/ROOT/pages/modules/bookmarks.adoc create mode 100644 docs/modules/ROOT/pages/modules/storage.adoc create mode 100644 docs/modules/ROOT/pages/modules/trino.adoc create mode 100644 docs/modules/ROOT/pages/reference/environment-variables.adoc diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 00000000..84234108 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,7 @@ +--- +name: cockpit +title: Stackable Cockpit +# Only the main branch is published, so there is a single version (like stackablectl). +version: 'nightly' +nav: + - modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 00000000..b1e17b16 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,13 @@ +* xref:index.adoc[] +* xref:getting-started.adoc[] +* Installation +** xref:installation/helm.adoc[] +** xref:installation/database.adoc[] +** xref:installation/authentication.adoc[] +** xref:installation/monitoring.adoc[] +* Modules +** xref:modules/trino.adoc[] +** xref:modules/storage.adoc[] +** xref:modules/bookmarks.adoc[] +* Reference +** xref:reference/environment-variables.adoc[] diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc new file mode 100644 index 00000000..d7b52ca1 --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -0,0 +1,51 @@ += Getting started +:description: Install Stackable Cockpit on Kubernetes with Helm, connect it to an OIDC provider, PostgreSQL and Trino, and run your first SQL query. + +This guide installs Cockpit with Helm and runs a first Trino query. +You need an existing PostgreSQL database, an OIDC client for Cockpit and a Trino cluster. + +// TODO: Replace the local chart path once the chart is published. + +Create a Secret with the database password and the OIDC client secret: + +[source,console] +---- +$ kubectl create secret generic cockpit \ + --from-literal=database-password='' \ + --from-literal=oidc-client-secret='' +---- + +Create a values file `cockpit-values.yaml`: + +[source,yaml] +---- +origin: https://cockpit.example.com # <1> +auth: + baseUrl: https://cockpit.example.com + oidc: + discoveryUrl: https://keycloak.example.com/realms/sdp/.well-known/openid-configuration + clientId: cockpit + clientSecret: + secretKeyRef: + name: cockpit +database: + host: postgresql + password: + secretKeyRef: + name: cockpit +trino: + url: https://trino-coordinator:8443 + tls: + secretClass: tls # <2> +---- +<1> The URL users open in the browser. It must use HTTPS, see xref:installation/helm.adoc#_ingress_and_reverse_proxy[Ingress and reverse proxy]. +<2> The SecretClass that provides the CA certificate of Trino. + +Install the chart: + +[source,console] +---- +$ helm install cockpit ./deploy/helm/cockpit --values cockpit-values.yaml +---- + +Open the URL in a browser, log in, select *Trino* in the sidebar and run a query such as `SELECT * FROM system.runtime.nodes`. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..48a13a47 --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,26 @@ += Stackable Cockpit +:description: Stackable Cockpit is a web UI for the Stackable Data Platform with a Trino SQL editor, an S3 storage browser and a dashboard with bookmarks. +:github: https://github.com/stackabletech/cockpit/ + +[.link-bar] +* {github}[GitHub {external-link-icon}^] + +Stackable Cockpit is a web UI for the Stackable Data Platform (SDP). +Users log in once through OpenID Connect (OIDC) and work with the platform's services from a single place. + +== Getting started + +Follow the xref:getting-started.adoc[] guide to install Cockpit with Helm and run your first Trino query. + +== Modules + +Cockpit consists of modules, and more are added over time: + +* xref:modules/trino.adoc[Trino]: a SQL editor with code completion and a schema browser. +* xref:modules/storage.adoc[Storage]: a file browser for S3-compatible object storage. +* xref:modules/bookmarks.adoc[Bookmarks]: links to frequently used tools on the dashboard. + +== Architecture + +Cockpit is a Node.js server that connects to Trino and S3 on behalf of the logged-in user. +It stores users, sessions, bookmarks and storage connections in PostgreSQL. diff --git a/docs/modules/ROOT/pages/installation/authentication.adoc b/docs/modules/ROOT/pages/installation/authentication.adoc new file mode 100644 index 00000000..efff77ee --- /dev/null +++ b/docs/modules/ROOT/pages/installation/authentication.adoc @@ -0,0 +1,30 @@ += Authentication +:description: Configure login to Stackable Cockpit with any OpenID Connect provider, such as Keycloak, including callback URL, scopes and session secret. + +Users log in to Cockpit through an OpenID Connect (OIDC) provider, for example Keycloak. +Register a confidential client for Cockpit with the redirect URI `/api/auth/oauth2/callback/oidc`. + +[source,yaml] +---- +auth: + baseUrl: https://cockpit.example.com # <1> + oidc: + discoveryUrl: https://keycloak.example.com/realms/sdp/.well-known/openid-configuration + clientId: cockpit + clientSecret: + secretKeyRef: + name: cockpit + key: oidc-client-secret + extraScopes: [] # <2> +sessionSecret: + secretKeyRef: + name: "" # <3> +---- +<1> The URL users open in the browser. +<2> Scopes requested in addition to `openid`, `profile` and `email`. +<3> The secret that signs session cookies. The chart generates one if empty. + +The OIDC claim that becomes the Trino user is configured in the xref:modules/trino.adoc#_user_identity[Trino module]. + +WARNING: With `auth.oidc.enabled: false`, Cockpit has no login and all visitors share one anonymous user. +Use this only for local testing. diff --git a/docs/modules/ROOT/pages/installation/database.adoc b/docs/modules/ROOT/pages/installation/database.adoc new file mode 100644 index 00000000..37bbb887 --- /dev/null +++ b/docs/modules/ROOT/pages/installation/database.adoc @@ -0,0 +1,23 @@ += Database +:description: Connect Stackable Cockpit to PostgreSQL, which stores users, sessions, bookmarks and storage connections, and configure TLS for the connection. + +Cockpit requires a PostgreSQL database for users, sessions, bookmarks and storage connections. +It creates and migrates its tables on startup. + +[source,yaml] +---- +database: + host: postgresql + port: 5432 + name: cockpit + user: cockpit + password: + secretKeyRef: + name: cockpit + key: database-password + tls: + mode: verify-full # <1> + secretClass: tls # <2> +---- +<1> `verify-full` (default), `require` (encrypt without verification) or `disable`. +<2> Provides the CA certificate of PostgreSQL. Alternatively set `caCert` to a mounted file. Both require `verify-full`. diff --git a/docs/modules/ROOT/pages/installation/helm.adoc b/docs/modules/ROOT/pages/installation/helm.adoc new file mode 100644 index 00000000..00596114 --- /dev/null +++ b/docs/modules/ROOT/pages/installation/helm.adoc @@ -0,0 +1,68 @@ += Helm chart +:description: Install Stackable Cockpit with its Helm chart and configure ingress, reverse proxy headers, CA certificates and the scratch volume. + +The Helm chart in `deploy/helm/cockpit` deploys Cockpit. +It does not deploy PostgreSQL, the OIDC provider or Trino. +The chart README lists all values. + +// TODO: Link the chart README and Helm repository once published. + +== Ingress and reverse proxy + +IMPORTANT: Cockpit must be served over HTTPS, because session cookies and credentials such as S3 keys pass through the browser connection. +Cockpit itself serves plain HTTP, so terminate TLS at the Ingress or reverse proxy and use `https://` URLs for `origin` and `auth.baseUrl`. + +The chart creates a ClusterIP Service on port 3000 and can create an Ingress with the `ingress` values. +Set `origin` to the URL users open in the browser. +Behind a reverse proxy, also set the forwarded headers Cockpit trusts: + +[source,yaml] +---- +origin: https://cockpit.example.com +proxy: + protocolHeader: x-forwarded-proto + hostHeader: x-forwarded-host +---- + +== CA certificates + +For backends with a private CA, set either a SecretClass or the path of a mounted CA file: + +[source,yaml] +---- +trino: + tls: + secretClass: tls # <1> +database: + tls: + caCert: /stackable/database-ca/ca.crt # <2> +extraVolumes: + - name: database-ca + secret: + secretName: database-ca +extraVolumeMounts: + - name: database-ca + mountPath: /stackable/database-ca + readOnly: true +---- +<1> The Secret Operator mounts the CA certificate of the SecretClass. +<2> A CA file mounted from a Secret. + +The same options exist under `storage.tls` for S3 endpoints. + +== Additional environment variables + +To set xref:reference/environment-variables.adoc[environment variables] directly, use `extraEnv` or `extraEnvFrom`: + +[source,yaml] +---- +extraEnv: + - name: LOG_LEVEL + value: debug +---- + +== Replicas + +Cockpit keeps running queries in memory, so keep `replicaCount` at `1`. + +// TODO: Remove once query state is shared between replicas. diff --git a/docs/modules/ROOT/pages/installation/monitoring.adoc b/docs/modules/ROOT/pages/installation/monitoring.adoc new file mode 100644 index 00000000..f368df55 --- /dev/null +++ b/docs/modules/ROOT/pages/installation/monitoring.adoc @@ -0,0 +1,10 @@ += Monitoring +:description: Stackable Cockpit exposes Prometheus metrics at /metrics and a health endpoint at /healthz, and writes structured JSON logs. + +Cockpit exposes Prometheus metrics at `/metrics` on port 3000, without authentication. +They include HTTP request durations, Trino query counts and storage operation metrics. + +The chart's liveness, readiness and startup probes use `/healthz`. + +Cockpit writes JSON logs to stdout. +Set the log level with `logging.level`; the default is `info`. diff --git a/docs/modules/ROOT/pages/modules/bookmarks.adoc b/docs/modules/ROOT/pages/modules/bookmarks.adoc new file mode 100644 index 00000000..7d6c4988 --- /dev/null +++ b/docs/modules/ROOT/pages/modules/bookmarks.adoc @@ -0,0 +1,30 @@ += Bookmarks +:description: The dashboard of Stackable Cockpit shows bookmarks to the web UIs of the platform's services, set up by each user or globally by the administrator. + +The dashboard and the sidebar show bookmarks to frequently used tools, such as the web UIs of the platform's services. +Each user can add up to 25 bookmarks of their own. +Pinned bookmarks appear under _Favourites_ at the top of the sidebar. + +== Global bookmarks + +Global bookmarks are shown to every user, before their own bookmarks. +Users cannot change them. + +[source,yaml] +---- +features: + bookmarks: + global: + - productId: superset # <1> + name: Dashboards # <2> + url: https://superset.example.com # <3> + environment: prod # <4> + pinned: true # <5> +---- +<1> One of `trino`, `superset`, `airflow`, `nifi`, `druid`, `opensearch`, `hdfs`, `hbase`, `spark` or `custom`. It selects the icon; unknown values are shown as `custom`. +<2> Up to 40 characters. +<3> An HTTP or HTTPS URL. +<4> Optional. A label shown on the bookmark, up to 100 characters. +<5> Optional. Shows the bookmark under _Favourites_. Defaults to `false`. + +Cockpit does not start if an entry is invalid. diff --git a/docs/modules/ROOT/pages/modules/storage.adoc b/docs/modules/ROOT/pages/modules/storage.adoc new file mode 100644 index 00000000..fd057e61 --- /dev/null +++ b/docs/modules/ROOT/pages/modules/storage.adoc @@ -0,0 +1,54 @@ += Storage +:description: The storage module of Stackable Cockpit is a file browser for S3-compatible object storage with previews, uploads, downloads and file editing. + +The storage module is a file browser for S3-compatible object storage. +Users browse buckets, upload and download files, preview common formats such as CSV, Parquet, images, PDFs and archives, and edit text files. + +The module is disabled by default: + +[source,yaml] +---- +features: + storage: + enabled: true +storage: + encryptionKey: + secretKeyRef: + name: cockpit + key: storage-encryption-key # <1> + tls: + secretClass: tls # <2> +---- +<1> A 64-character hex string, for example from `openssl rand -hex 32`. +<2> Optional. Provides the CA certificate of the S3 endpoints. Alternatively set `caCert` to a mounted file. + +Each user adds their own S3 connections in the UI. +Cockpit stores them in the database, with the credentials encrypted by the encryption key. +If the key changes or is lost, the stored credentials can no longer be read. + +The CA certificate in `storage.tls` replaces the system trust store, so endpoints with publicly trusted certificates fail while it is set. + +== File operations + +Cut, copy, paste, rename and drag-and-drop move are disabled by default, because they can cause many S3 requests: + +[source,yaml] +---- +features: + storage: + transfer: true +---- + +== Limits + +Preview sizes, upload and transfer concurrency, the archive cache and the download history retention are set under `storage`, see the xref:reference/environment-variables.adoc#_storage[reference]: + +[source,yaml] +---- +storage: + filePreviewRows: 500 + maxEditableFileSize: 10485760 # <1> +config: + bodySizeLimit: 12M +---- +<1> `config.bodySizeLimit` must be at least this large, otherwise saving large files fails. diff --git a/docs/modules/ROOT/pages/modules/trino.adoc b/docs/modules/ROOT/pages/modules/trino.adoc new file mode 100644 index 00000000..c0e9679a --- /dev/null +++ b/docs/modules/ROOT/pages/modules/trino.adoc @@ -0,0 +1,45 @@ += Trino +:description: The Trino module of Stackable Cockpit is a SQL editor with code completion and a schema browser that runs queries as the logged-in user. + +The Trino module is a SQL editor for xref:home:trino:index.adoc[Trino] with syntax highlighting, code completion and a schema browser. + +== Connection + +Set `trino.url` to connect all users to one Trino cluster: + +[source,yaml] +---- +trino: + url: https://trino-coordinator:8443 # <1> + publicUrl: https://trino.example.com # <2> + auth: + type: basic # <3> + username: cockpit + password: + secretKeyRef: + name: cockpit + key: trino-auth-password + tls: + secretClass: tls # <4> +---- +<1> The coordinator as Cockpit reaches it. +<2> Optional. The URL for links to the Trino web UI, defaults to `url`. +<3> `none` (default) or `basic`. +<4> Provides the CA certificate of Trino. Alternatively set `caCert` to a mounted file, or `insecure: true` to skip verification. + +Without `trino.url`, each user enters a connection in the UI. +These connections are kept in memory and are lost when Cockpit restarts. + +== User identity + +Cockpit sends queries with the logged-in user as `X-Trino-User`, so Trino applies its access control to that user. +The user is taken from the OIDC claim `trino.userImpersonation.userClaim` (default `preferred_username`), and updated on every login. +If the claim is missing, Cockpit uses `preferred_username`, then the email address. +With basic authentication, Trino must allow the Cockpit user to impersonate other users. + +Set `trino.userImpersonation.enabled: false` to run all queries as `trino.auth.username` instead. + +== Settings + +* `features.trino.completion.enabled` turns code completion on or off (default `true`). +* `trino.queryTtl` sets how long, in seconds, finished queries of an unused editor tab are kept (default `1800`). diff --git a/docs/modules/ROOT/pages/reference/environment-variables.adoc b/docs/modules/ROOT/pages/reference/environment-variables.adoc new file mode 100644 index 00000000..9480b5b8 --- /dev/null +++ b/docs/modules/ROOT/pages/reference/environment-variables.adoc @@ -0,0 +1,243 @@ += Environment variables +:description: Reference of all environment variables that configure Stackable Cockpit, with their defaults, grouped by server, authentication, Trino and storage. + +The Helm chart sets these variables from its values. +Set them directly only when you run Cockpit without the chart. +Cockpit does not start if a value is invalid, and the error names every invalid variable. + +// TODO: Generate this page from the code so it cannot drift. + +== Server + +[cols="2,1,3"] +|=== +|Variable |Default |Description + +|`ORIGIN` +| +|The URL users open in the browser. Requests from other origins are rejected. + +|`PROTOCOL_HEADER`, `HOST_HEADER` +| +|Forwarded headers trusted behind a reverse proxy, for example `x-forwarded-proto` and `x-forwarded-host`. + +|`BODY_SIZE_LIMIT` +|`6M` +|Maximum request body size. + +|`LOG_LEVEL` +|`info` +|`trace`, `debug`, `info`, `warn` or `error`. +|=== + +== Database + +[cols="2,1,3"] +|=== +|Variable |Default |Description + +|`DATABASE_HOST` +|`localhost` +|PostgreSQL host. + +|`DATABASE_PORT` +|`31432` +|PostgreSQL port. + +|`DATABASE_NAME` +|`cockpit` +|Database name. + +|`DATABASE_USER` +|`cockpit` +|Database user. + +|`DATABASE_PASSWORD` +| +|Database password. Required. + +|`DATABASE_TLS_MODE` +|`verify-full` in production, otherwise `disable` +|`verify-full`, `require` or `disable`. + +|`DATABASE_TLS_CA_CERT` +| +|Path to the CA certificate of PostgreSQL. Requires `verify-full`. +|=== + +== Authentication + +[cols="2,1,3"] +|=== +|Variable |Default |Description + +|`STACKABLE_COCKPIT_BASE_URL` +| +|The URL users open in the browser, used for the OIDC callback. + +|`STACKABLE_COCKPIT_SESSION_SECRET` +| +|Secret that signs session cookies. + +|`STACKABLE_COCKPIT_OIDC_DISCOVERY_URL` +| +|The `.well-known/openid-configuration` URL of the OIDC provider. Login is disabled unless this, the client ID and the client secret are set. + +|`STACKABLE_COCKPIT_OIDC_CLIENT_ID` +| +|OIDC client ID. + +|`STACKABLE_COCKPIT_OIDC_CLIENT_SECRET` +| +|OIDC client secret. + +|`STACKABLE_COCKPIT_OIDC_EXTRA_SCOPES` +| +|Scopes requested in addition to `openid`, `profile` and `email`, separated by commas or spaces. +|=== + +== Trino + +[cols="2,1,3"] +|=== +|Variable |Default |Description + +|`STACKABLE_COCKPIT_TRINO_URL` +| +|Trino coordinator URL for all users. Without it, users enter a connection in the UI. + +|`STACKABLE_COCKPIT_TRINO_PUBLIC_URL` +|`STACKABLE_COCKPIT_TRINO_URL` +|URL for links to the Trino web UI. + +|`STACKABLE_COCKPIT_TRINO_AUTH_TYPE` +|`none` +|`none` or `basic`. + +|`STACKABLE_COCKPIT_TRINO_AUTH_USERNAME` +| +|User for basic authentication. + +|`STACKABLE_COCKPIT_TRINO_AUTH_PASSWORD` +| +|Password for basic authentication. + +|`STACKABLE_COCKPIT_TRINO_TLS_CA_CERT` +| +|Path to the CA certificate of Trino. + +|`STACKABLE_COCKPIT_TRINO_TLS_INSECURE` +|`false` +|Skip TLS certificate verification. + +|`STACKABLE_COCKPIT_TRINO_USER_IMPERSONATION` +|`true` +|Send queries as the logged-in user. + +|`STACKABLE_COCKPIT_TRINO_USER_CLAIM` +|`preferred_username` +|OIDC claim used as the Trino user. + +|`STACKABLE_COCKPIT_COMPLETION_ENABLED` +|`true` +|SQL code completion. + +|`STACKABLE_COCKPIT_QUERY_TTL` +|`1800` +|Seconds that finished queries of an unused editor tab are kept. +|=== + +== Storage + +[cols="2,1,3"] +|=== +|Variable |Default |Description + +|`STACKABLE_COCKPIT_STORAGE_BROWSER_ENABLED` +|`false` +|Enables the storage module. + +|`STORAGE_ENCRYPTION_KEY` +| +|64-character hex key that encrypts stored S3 credentials. Required when the storage module is enabled. + +|`STACKABLE_COCKPIT_STORAGE_TLS_CA_CERT` +| +|Path to the CA certificate of the S3 endpoints. Replaces the system trust store. + +|`PUBLIC_STACKABLE_COCKPIT_STORAGE_TRANSFER_ENABLED` +|`false` +|Cut, copy, paste, rename and drag-and-drop move. + +|`PUBLIC_STACKABLE_COCKPIT_PAGE_SIZES` +|`25,50,100` +|Page sizes of paginated lists. + +|`PUBLIC_STACKABLE_COCKPIT_DEFAULT_PAGE_SIZE` +|Smallest page size +|Default page size. Must be one of the page sizes. + +|`PUBLIC_STACKABLE_COCKPIT_MAX_RECENT_FILES` +|`15` +|Recently visited locations kept in the browser. + +|`PUBLIC_STACKABLE_COCKPIT_UPLOAD_CONCURRENCY` +|`3` +|Parallel requests during uploads. + +|`PUBLIC_STACKABLE_COCKPIT_MAX_EDITABLE_FILE_SIZE` +|`5242880` +|Largest file in bytes that can be edited. `BODY_SIZE_LIMIT` must be at least this large. + +|`STACKABLE_COCKPIT_TEXT_PREVIEW_BYTES` +|`262144` +|Bytes fetched for text, TSV and JSON previews. + +|`STACKABLE_COCKPIT_IMAGE_PREVIEW_BYTES` +|`5242880` +|Bytes fetched for image previews. + +|`STACKABLE_COCKPIT_PDF_PREVIEW_BYTES` +|`26214400` +|Bytes fetched for PDF previews. + +|`STACKABLE_COCKPIT_FILE_PREVIEW_ROWS` +|`250` +|Rows in tabular previews. + +|`STACKABLE_COCKPIT_FILE_PREVIEW_COLUMNS` +|`50` +|Columns in tabular previews. + +|`STACKABLE_COCKPIT_PARQUET_PREVIEW_DISALLOWED_COMPRESSION_TYPES` +|`gzip-no_offset` +|Parquet codecs that are not previewed. The suffix `-no_offset` blocks only files without an offset index. + +|`STACKABLE_COCKPIT_ARCHIVE_PREVIEW_MAX_MB` +|`100` +|Largest archive in MB that is previewed. + +|`STACKABLE_COCKPIT_ARCHIVE_CACHE_MAX_MB` +|`512` +|Size in MB of the archive cache in `/tmp`. At least twice the archive preview limit. + +|`STACKABLE_COCKPIT_STORAGE_TRANSFER_CONCURRENCY` +|`8` +|Objects copied in parallel within one copy, move or rename. + +|`STACKABLE_COCKPIT_DOWNLOAD_HISTORY_RETENTION_DAYS` +|`30` +|Days the download history is kept, from 1 to 3650. +|=== + +== Bookmarks + +[cols="2,1,3"] +|=== +|Variable |Default |Description + +|`STACKABLE_COCKPIT_GLOBAL_BOOKMARKS` +| +|JSON array of bookmarks shown to every user, see xref:modules/bookmarks.adoc#_global_bookmarks[Global bookmarks]. +Example: `[{"productId":"superset","name":"Dashboards","url":"https://superset.example.com"}]`. +|=== From 6d08dfdd6ce7d6b6fc1e068bc1a0f0e97dd587c0 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 2 Nov 2026 11:41:14 +0100 Subject: [PATCH 02/13] docs: Version the docs with the SDP like the operators Cockpit is released together with the SDP, so the docs become the 'cockpit' module of the 'home' component instead of a component of their own. The release scripts set the version on release branches. --- docs/antora.yml | 11 +++++------ docs/modules/ROOT/nav.adoc | 13 ------------- .../{ROOT => cockpit}/pages/getting-started.adoc | 0 docs/modules/{ROOT => cockpit}/pages/index.adoc | 0 .../pages/installation/authentication.adoc | 0 .../pages/installation/database.adoc | 0 .../{ROOT => cockpit}/pages/installation/helm.adoc | 0 .../pages/installation/monitoring.adoc | 0 .../{ROOT => cockpit}/pages/modules/bookmarks.adoc | 0 .../{ROOT => cockpit}/pages/modules/storage.adoc | 0 .../{ROOT => cockpit}/pages/modules/trino.adoc | 2 +- .../pages/reference/environment-variables.adoc | 0 docs/modules/cockpit/partials/nav.adoc | 12 ++++++++++++ 13 files changed, 18 insertions(+), 20 deletions(-) delete mode 100644 docs/modules/ROOT/nav.adoc rename docs/modules/{ROOT => cockpit}/pages/getting-started.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/index.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/installation/authentication.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/installation/database.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/installation/helm.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/installation/monitoring.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/modules/bookmarks.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/modules/storage.adoc (100%) rename docs/modules/{ROOT => cockpit}/pages/modules/trino.adoc (92%) rename docs/modules/{ROOT => cockpit}/pages/reference/environment-variables.adoc (100%) create mode 100644 docs/modules/cockpit/partials/nav.adoc diff --git a/docs/antora.yml b/docs/antora.yml index 84234108..5c1d73fb 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,7 +1,6 @@ --- -name: cockpit -title: Stackable Cockpit -# Only the main branch is published, so there is a single version (like stackablectl). -version: 'nightly' -nav: - - modules/ROOT/nav.adoc +# Cockpit is a module of the 'home' component, like the operators. +# The release scripts set the version to YY.M and prerelease to false on release branches. +name: home +version: "nightly" +prerelease: true diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc deleted file mode 100644 index b1e17b16..00000000 --- a/docs/modules/ROOT/nav.adoc +++ /dev/null @@ -1,13 +0,0 @@ -* xref:index.adoc[] -* xref:getting-started.adoc[] -* Installation -** xref:installation/helm.adoc[] -** xref:installation/database.adoc[] -** xref:installation/authentication.adoc[] -** xref:installation/monitoring.adoc[] -* Modules -** xref:modules/trino.adoc[] -** xref:modules/storage.adoc[] -** xref:modules/bookmarks.adoc[] -* Reference -** xref:reference/environment-variables.adoc[] diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/cockpit/pages/getting-started.adoc similarity index 100% rename from docs/modules/ROOT/pages/getting-started.adoc rename to docs/modules/cockpit/pages/getting-started.adoc diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/cockpit/pages/index.adoc similarity index 100% rename from docs/modules/ROOT/pages/index.adoc rename to docs/modules/cockpit/pages/index.adoc diff --git a/docs/modules/ROOT/pages/installation/authentication.adoc b/docs/modules/cockpit/pages/installation/authentication.adoc similarity index 100% rename from docs/modules/ROOT/pages/installation/authentication.adoc rename to docs/modules/cockpit/pages/installation/authentication.adoc diff --git a/docs/modules/ROOT/pages/installation/database.adoc b/docs/modules/cockpit/pages/installation/database.adoc similarity index 100% rename from docs/modules/ROOT/pages/installation/database.adoc rename to docs/modules/cockpit/pages/installation/database.adoc diff --git a/docs/modules/ROOT/pages/installation/helm.adoc b/docs/modules/cockpit/pages/installation/helm.adoc similarity index 100% rename from docs/modules/ROOT/pages/installation/helm.adoc rename to docs/modules/cockpit/pages/installation/helm.adoc diff --git a/docs/modules/ROOT/pages/installation/monitoring.adoc b/docs/modules/cockpit/pages/installation/monitoring.adoc similarity index 100% rename from docs/modules/ROOT/pages/installation/monitoring.adoc rename to docs/modules/cockpit/pages/installation/monitoring.adoc diff --git a/docs/modules/ROOT/pages/modules/bookmarks.adoc b/docs/modules/cockpit/pages/modules/bookmarks.adoc similarity index 100% rename from docs/modules/ROOT/pages/modules/bookmarks.adoc rename to docs/modules/cockpit/pages/modules/bookmarks.adoc diff --git a/docs/modules/ROOT/pages/modules/storage.adoc b/docs/modules/cockpit/pages/modules/storage.adoc similarity index 100% rename from docs/modules/ROOT/pages/modules/storage.adoc rename to docs/modules/cockpit/pages/modules/storage.adoc diff --git a/docs/modules/ROOT/pages/modules/trino.adoc b/docs/modules/cockpit/pages/modules/trino.adoc similarity index 92% rename from docs/modules/ROOT/pages/modules/trino.adoc rename to docs/modules/cockpit/pages/modules/trino.adoc index c0e9679a..dae6351c 100644 --- a/docs/modules/ROOT/pages/modules/trino.adoc +++ b/docs/modules/cockpit/pages/modules/trino.adoc @@ -1,7 +1,7 @@ = Trino :description: The Trino module of Stackable Cockpit is a SQL editor with code completion and a schema browser that runs queries as the logged-in user. -The Trino module is a SQL editor for xref:home:trino:index.adoc[Trino] with syntax highlighting, code completion and a schema browser. +The Trino module is a SQL editor for xref:trino:index.adoc[Trino] with syntax highlighting, code completion and a schema browser. == Connection diff --git a/docs/modules/ROOT/pages/reference/environment-variables.adoc b/docs/modules/cockpit/pages/reference/environment-variables.adoc similarity index 100% rename from docs/modules/ROOT/pages/reference/environment-variables.adoc rename to docs/modules/cockpit/pages/reference/environment-variables.adoc diff --git a/docs/modules/cockpit/partials/nav.adoc b/docs/modules/cockpit/partials/nav.adoc new file mode 100644 index 00000000..dc41859b --- /dev/null +++ b/docs/modules/cockpit/partials/nav.adoc @@ -0,0 +1,12 @@ +* xref:cockpit:getting-started.adoc[] +* Installation +** xref:cockpit:installation/helm.adoc[] +** xref:cockpit:installation/database.adoc[] +** xref:cockpit:installation/authentication.adoc[] +** xref:cockpit:installation/monitoring.adoc[] +* Modules +** xref:cockpit:modules/trino.adoc[] +** xref:cockpit:modules/storage.adoc[] +** xref:cockpit:modules/bookmarks.adoc[] +* Reference +** xref:cockpit:reference/environment-variables.adoc[] From daccaeab51d5c31f7d421b891649e12b5d437387 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 2 Nov 2026 13:04:40 +0100 Subject: [PATCH 03/13] docs: Install the published Helm chart --- docs/modules/cockpit/pages/getting-started.adoc | 4 ++-- docs/modules/cockpit/pages/installation/helm.adoc | 10 +++++++--- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/modules/cockpit/pages/getting-started.adoc b/docs/modules/cockpit/pages/getting-started.adoc index d7b52ca1..e45e1152 100644 --- a/docs/modules/cockpit/pages/getting-started.adoc +++ b/docs/modules/cockpit/pages/getting-started.adoc @@ -43,9 +43,9 @@ trino: Install the chart: -[source,console] +[source,console,subs="attributes"] ---- -$ helm install cockpit ./deploy/helm/cockpit --values cockpit-values.yaml +$ helm install cockpit oci://oci.stackable.tech/sdp-charts/cockpit --version {stackable-operator-version} --values cockpit-values.yaml ---- Open the URL in a browser, log in, select *Trino* in the sidebar and run a query such as `SELECT * FROM system.runtime.nodes`. diff --git a/docs/modules/cockpit/pages/installation/helm.adoc b/docs/modules/cockpit/pages/installation/helm.adoc index 00596114..e5c4affc 100644 --- a/docs/modules/cockpit/pages/installation/helm.adoc +++ b/docs/modules/cockpit/pages/installation/helm.adoc @@ -1,11 +1,15 @@ = Helm chart :description: Install Stackable Cockpit with its Helm chart and configure ingress, reverse proxy headers, CA certificates and the scratch volume. -The Helm chart in `deploy/helm/cockpit` deploys Cockpit. +The Helm chart deploys Cockpit. It does not deploy PostgreSQL, the OIDC provider or Trino. -The chart README lists all values. +The chart is published to `oci.stackable.tech/sdp-charts/cockpit`. +The https://github.com/stackabletech/cockpit/blob/{stackable-operator-branch}/deploy/helm/cockpit/README.md[chart README{external-link-icon}^] lists all values. -// TODO: Link the chart README and Helm repository once published. +[source,console,subs="attributes"] +---- +$ helm install cockpit oci://oci.stackable.tech/sdp-charts/cockpit --version {stackable-operator-version} --values cockpit-values.yaml +---- == Ingress and reverse proxy From 51be4e39e384b2038b54b6df4f241a8f940d08bd Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 2 Nov 2026 13:08:32 +0100 Subject: [PATCH 04/13] style(docs): Use single quotes in antora.yml --- docs/antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/antora.yml b/docs/antora.yml index 5c1d73fb..8bafce5c 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -2,5 +2,5 @@ # Cockpit is a module of the 'home' component, like the operators. # The release scripts set the version to YY.M and prerelease to false on release branches. name: home -version: "nightly" +version: 'nightly' prerelease: true From d3c507350e2915910bedadc7b8a93540389f7a81 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 2 Nov 2026 14:58:54 +0100 Subject: [PATCH 05/13] docs: Fix bookmark key and database TLS in getting started --- docs/modules/cockpit/pages/getting-started.adoc | 9 +++++---- docs/modules/cockpit/pages/modules/bookmarks.adoc | 15 +++++++-------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/modules/cockpit/pages/getting-started.adoc b/docs/modules/cockpit/pages/getting-started.adoc index e45e1152..d3c656a2 100644 --- a/docs/modules/cockpit/pages/getting-started.adoc +++ b/docs/modules/cockpit/pages/getting-started.adoc @@ -4,8 +4,6 @@ This guide installs Cockpit with Helm and runs a first Trino query. You need an existing PostgreSQL database, an OIDC client for Cockpit and a Trino cluster. -// TODO: Replace the local chart path once the chart is published. - Create a Secret with the database password and the OIDC client secret: [source,console] @@ -33,13 +31,16 @@ database: password: secretKeyRef: name: cockpit + tls: + secretClass: tls # <2> trino: url: https://trino-coordinator:8443 tls: - secretClass: tls # <2> + secretClass: tls # <3> ---- <1> The URL users open in the browser. It must use HTTPS, see xref:installation/helm.adoc#_ingress_and_reverse_proxy[Ingress and reverse proxy]. -<2> The SecretClass that provides the CA certificate of Trino. +<2> The SecretClass that provides the CA certificate of PostgreSQL. Cockpit verifies the certificate by default, see xref:installation/database.adoc[]. +<3> The SecretClass that provides the CA certificate of Trino. Install the chart: diff --git a/docs/modules/cockpit/pages/modules/bookmarks.adoc b/docs/modules/cockpit/pages/modules/bookmarks.adoc index 7d6c4988..5849446b 100644 --- a/docs/modules/cockpit/pages/modules/bookmarks.adoc +++ b/docs/modules/cockpit/pages/modules/bookmarks.adoc @@ -12,14 +12,13 @@ Users cannot change them. [source,yaml] ---- -features: - bookmarks: - global: - - productId: superset # <1> - name: Dashboards # <2> - url: https://superset.example.com # <3> - environment: prod # <4> - pinned: true # <5> +bookmarks: + global: + - productId: superset # <1> + name: Dashboards # <2> + url: https://superset.example.com # <3> + environment: prod # <4> + pinned: true # <5> ---- <1> One of `trino`, `superset`, `airflow`, `nifi`, `druid`, `opensearch`, `hdfs`, `hbase`, `spark` or `custom`. It selects the icon; unknown values are shown as `custom`. <2> Up to 40 characters. From 5b0e502dddbf55e0bb6d8ec5c551fa455f431566 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 2 Nov 2026 15:00:32 +0100 Subject: [PATCH 06/13] docs: Add the OIDC redirect URI to getting started --- docs/modules/cockpit/pages/getting-started.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/modules/cockpit/pages/getting-started.adoc b/docs/modules/cockpit/pages/getting-started.adoc index d3c656a2..5c637447 100644 --- a/docs/modules/cockpit/pages/getting-started.adoc +++ b/docs/modules/cockpit/pages/getting-started.adoc @@ -3,6 +3,7 @@ This guide installs Cockpit with Helm and runs a first Trino query. You need an existing PostgreSQL database, an OIDC client for Cockpit and a Trino cluster. +Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/oauth2/callback/oidc`, see xref:installation/authentication.adoc[]. Create a Secret with the database password and the OIDC client secret: From 5e418262a4d02b1c5c088dc8e558b8c4214d97b0 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 2 Nov 2026 15:04:16 +0100 Subject: [PATCH 07/13] docs: Address review findings --- docs/modules/cockpit/pages/index.adoc | 2 +- .../pages/installation/authentication.adoc | 3 ++- docs/modules/cockpit/pages/installation/helm.adoc | 15 ++++++++++++++- .../pages/reference/environment-variables.adoc | 8 ++++++++ 4 files changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/modules/cockpit/pages/index.adoc b/docs/modules/cockpit/pages/index.adoc index 48a13a47..01ee96cb 100644 --- a/docs/modules/cockpit/pages/index.adoc +++ b/docs/modules/cockpit/pages/index.adoc @@ -22,5 +22,5 @@ Cockpit consists of modules, and more are added over time: == Architecture -Cockpit is a Node.js server that connects to Trino and S3 on behalf of the logged-in user. +Cockpit is a Node.js server that connects to Trino as the logged-in user and to S3 with the connections each user configures. It stores users, sessions, bookmarks and storage connections in PostgreSQL. diff --git a/docs/modules/cockpit/pages/installation/authentication.adoc b/docs/modules/cockpit/pages/installation/authentication.adoc index efff77ee..3bda95cb 100644 --- a/docs/modules/cockpit/pages/installation/authentication.adoc +++ b/docs/modules/cockpit/pages/installation/authentication.adoc @@ -22,7 +22,8 @@ sessionSecret: ---- <1> The URL users open in the browser. <2> Scopes requested in addition to `openid`, `profile` and `email`. -<3> The secret that signs session cookies. The chart generates one if empty. +<3> The secret that signs session cookies. The chart generates one if empty and keeps it across `helm upgrade`. +Set it explicitly when deploying with `helm template` or Argo CD, which cannot read the existing Secret, otherwise every deployment logs out all users. The OIDC claim that becomes the Trino user is configured in the xref:modules/trino.adoc#_user_identity[Trino module]. diff --git a/docs/modules/cockpit/pages/installation/helm.adoc b/docs/modules/cockpit/pages/installation/helm.adoc index e5c4affc..67254ee6 100644 --- a/docs/modules/cockpit/pages/installation/helm.adoc +++ b/docs/modules/cockpit/pages/installation/helm.adoc @@ -65,8 +65,21 @@ extraEnv: value: debug ---- +== Scratch volume + +The chart mounts an emptyDir at `/tmp` for the archive preview cache. +Keep `tmp.sizeLimit` above `storage.archiveCacheMaxMb`, otherwise the kubelet evicts the pod when the cache fills up: + +[source,yaml] +---- +tmp: + sizeLimit: 1Gi +storage: + archiveCacheMaxMb: 512 +---- + == Replicas Cockpit keeps running queries in memory, so keep `replicaCount` at `1`. -// TODO: Remove once query state is shared between replicas. +// TODO: Remove once query state is shared between replicas, see https://github.com/stackabletech/cockpit/issues/310. diff --git a/docs/modules/cockpit/pages/reference/environment-variables.adoc b/docs/modules/cockpit/pages/reference/environment-variables.adoc index 9480b5b8..b1bf9406 100644 --- a/docs/modules/cockpit/pages/reference/environment-variables.adoc +++ b/docs/modules/cockpit/pages/reference/environment-variables.adoc @@ -13,6 +13,14 @@ Cockpit does not start if a value is invalid, and the error names every invalid |=== |Variable |Default |Description +|`NODE_ENV` +|`production` +|Set in the image. Other values switch to development defaults, such as no database TLS and `trace` logging. + +|`PORT` +|`3000` +|HTTP port Cockpit listens on. + |`ORIGIN` | |The URL users open in the browser. Requests from other origins are rejected. From 5e1e5dffcaa5eccbf46f76dd2efab2557d53e4fd Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Tue, 3 Nov 2026 08:41:53 +0100 Subject: [PATCH 08/13] docs: Document startup validation, logging variables and global bookmark rules --- docs/modules/cockpit/pages/modules/bookmarks.adoc | 4 ++-- docs/modules/cockpit/pages/modules/trino.adoc | 2 +- .../pages/reference/environment-variables.adoc | 12 ++++++++++-- 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/modules/cockpit/pages/modules/bookmarks.adoc b/docs/modules/cockpit/pages/modules/bookmarks.adoc index 5849446b..906fd3f1 100644 --- a/docs/modules/cockpit/pages/modules/bookmarks.adoc +++ b/docs/modules/cockpit/pages/modules/bookmarks.adoc @@ -22,8 +22,8 @@ bookmarks: ---- <1> One of `trino`, `superset`, `airflow`, `nifi`, `druid`, `opensearch`, `hdfs`, `hbase`, `spark` or `custom`. It selects the icon; unknown values are shown as `custom`. <2> Up to 40 characters. -<3> An HTTP or HTTPS URL. +<3> An HTTP or HTTPS URL without a user name or password. Every user can see it in the page source, so it must not contain a token or other secret either. <4> Optional. A label shown on the bookmark, up to 100 characters. <5> Optional. Shows the bookmark under _Favourites_. Defaults to `false`. -Cockpit does not start if an entry is invalid. +`bookmarks.global` must be a YAML list. diff --git a/docs/modules/cockpit/pages/modules/trino.adoc b/docs/modules/cockpit/pages/modules/trino.adoc index dae6351c..b56bf26b 100644 --- a/docs/modules/cockpit/pages/modules/trino.adoc +++ b/docs/modules/cockpit/pages/modules/trino.adoc @@ -24,7 +24,7 @@ trino: ---- <1> The coordinator as Cockpit reaches it. <2> Optional. The URL for links to the Trino web UI, defaults to `url`. -<3> `none` (default) or `basic`. +<3> `none` (default) or `basic`. Cockpit does not start with `basic` and no username or password. <4> Provides the CA certificate of Trino. Alternatively set `caCert` to a mounted file, or `insecure: true` to skip verification. Without `trino.url`, each user enters a connection in the UI. diff --git a/docs/modules/cockpit/pages/reference/environment-variables.adoc b/docs/modules/cockpit/pages/reference/environment-variables.adoc index b1bf9406..c1c3c819 100644 --- a/docs/modules/cockpit/pages/reference/environment-variables.adoc +++ b/docs/modules/cockpit/pages/reference/environment-variables.adoc @@ -36,6 +36,14 @@ Cockpit does not start if a value is invalid, and the error names every invalid |`LOG_LEVEL` |`info` |`trace`, `debug`, `info`, `warn` or `error`. + +|`LOG_PRETTY` +|`false` in production, otherwise `true` +|Human-readable instead of JSON logs on stdout. + +|`LOG_JSON_FILE` +| +|Path of a file that also receives the JSON logs, for example for a log collector. |=== == Database @@ -89,7 +97,7 @@ Cockpit does not start if a value is invalid, and the error names every invalid |`STACKABLE_COCKPIT_OIDC_DISCOVERY_URL` | -|The `.well-known/openid-configuration` URL of the OIDC provider. Login is disabled unless this, the client ID and the client secret are set. +|The `.well-known/openid-configuration` URL of the OIDC provider. Set this, the client ID and the client secret, or none of them. Without them, login is disabled; with only some, Cockpit does not start. |`STACKABLE_COCKPIT_OIDC_CLIENT_ID` | @@ -120,7 +128,7 @@ Cockpit does not start if a value is invalid, and the error names every invalid |`STACKABLE_COCKPIT_TRINO_AUTH_TYPE` |`none` -|`none` or `basic`. +|`none` or `basic`. With `basic` and `STACKABLE_COCKPIT_TRINO_URL`, the username and password are required. |`STACKABLE_COCKPIT_TRINO_AUTH_USERNAME` | From 9968d84ef98b04dfebe5f78a5b29a83e1b517f0b Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Tue, 3 Nov 2026 16:54:12 +0100 Subject: [PATCH 09/13] docs(trino): Document how Trino errors are shown --- docs/modules/cockpit/pages/modules/trino.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/modules/cockpit/pages/modules/trino.adoc b/docs/modules/cockpit/pages/modules/trino.adoc index b56bf26b..c6b88f8c 100644 --- a/docs/modules/cockpit/pages/modules/trino.adoc +++ b/docs/modules/cockpit/pages/modules/trino.adoc @@ -39,6 +39,12 @@ With basic authentication, Trino must allow the Cockpit user to impersonate othe Set `trino.userImpersonation.enabled: false` to run all queries as `trino.auth.username` instead. +== Errors + +Users see the Trino error message only for errors in their own query, such as a syntax error or a missing table. +For server-side errors, Cockpit shows a generic message, because the Trino message can contain hostnames or storage paths. +The full message is logged as a warning with the Trino query ID. + == Settings * `features.trino.completion.enabled` turns code completion on or off (default `true`). From d878b8e4eb378643cb06170d83a3d85ac61884d3 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Tue, 3 Nov 2026 16:54:12 +0100 Subject: [PATCH 10/13] docs(helm): Document that Cockpit must be served at the root path --- docs/modules/cockpit/pages/installation/helm.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/modules/cockpit/pages/installation/helm.adoc b/docs/modules/cockpit/pages/installation/helm.adoc index 67254ee6..e1d1b39e 100644 --- a/docs/modules/cockpit/pages/installation/helm.adoc +++ b/docs/modules/cockpit/pages/installation/helm.adoc @@ -17,6 +17,10 @@ IMPORTANT: Cockpit must be served over HTTPS, because session cookies and creden Cockpit itself serves plain HTTP, so terminate TLS at the Ingress or reverse proxy and use `https://` URLs for `origin` and `auth.baseUrl`. The chart creates a ClusterIP Service on port 3000 and can create an Ingress with the `ingress` values. + +Cockpit must be served at the root path `/` of its host, for example `https://cockpit.example.com/`. +Other base paths such as `https://example.com/cockpit/` are not supported, so do not route a path prefix to Cockpit or rewrite paths in the Ingress or reverse proxy. + Set `origin` to the URL users open in the browser. Behind a reverse proxy, also set the forwarded headers Cockpit trusts: From 5feb5f8ae701033937b92ee6527b0d2e115dd136 Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Wed, 4 Nov 2026 11:52:57 +0100 Subject: [PATCH 11/13] docs: Name the generated session Secret and list all prerequisites Getting started also needs the Secret Operator for the SecretClasses and an Ingress or reverse proxy that serves Cockpit over HTTPS. --- docs/modules/cockpit/pages/getting-started.adoc | 2 +- docs/modules/cockpit/pages/installation/authentication.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/cockpit/pages/getting-started.adoc b/docs/modules/cockpit/pages/getting-started.adoc index 5c637447..8ad991a5 100644 --- a/docs/modules/cockpit/pages/getting-started.adoc +++ b/docs/modules/cockpit/pages/getting-started.adoc @@ -2,7 +2,7 @@ :description: Install Stackable Cockpit on Kubernetes with Helm, connect it to an OIDC provider, PostgreSQL and Trino, and run your first SQL query. This guide installs Cockpit with Helm and runs a first Trino query. -You need an existing PostgreSQL database, an OIDC client for Cockpit and a Trino cluster. +You need an existing PostgreSQL database, an OIDC client for Cockpit, a Trino cluster, the Stackable Secret Operator and an Ingress or reverse proxy that serves `https://cockpit.example.com`. Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/oauth2/callback/oidc`, see xref:installation/authentication.adoc[]. Create a Secret with the database password and the OIDC client secret: diff --git a/docs/modules/cockpit/pages/installation/authentication.adoc b/docs/modules/cockpit/pages/installation/authentication.adoc index 3bda95cb..94ba18da 100644 --- a/docs/modules/cockpit/pages/installation/authentication.adoc +++ b/docs/modules/cockpit/pages/installation/authentication.adoc @@ -22,7 +22,7 @@ sessionSecret: ---- <1> The URL users open in the browser. <2> Scopes requested in addition to `openid`, `profile` and `email`. -<3> The secret that signs session cookies. The chart generates one if empty and keeps it across `helm upgrade`. +<3> The secret that signs session cookies. If empty, the chart generates a Secret (`cockpit-session` for the release `cockpit`) and keeps it across `helm upgrade`. Set it explicitly when deploying with `helm template` or Argo CD, which cannot read the existing Secret, otherwise every deployment logs out all users. The OIDC claim that becomes the Trino user is configured in the xref:modules/trino.adoc#_user_identity[Trino module]. From 6e046e8b558504144ebd296768b644fd7b9d00bc Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 9 Nov 2026 12:39:30 +0100 Subject: [PATCH 12/13] docs: Fix the OIDC redirect URI and Trino URL in examples better-auth 1.7 serves the generic OAuth callback at /api/auth/callback/oidc. The Trino TLS certificate from the Secret Operator covers the headless role group Service, not trino-coordinator. --- docs/modules/cockpit/pages/getting-started.adoc | 4 ++-- docs/modules/cockpit/pages/installation/authentication.adoc | 2 +- docs/modules/cockpit/pages/modules/trino.adoc | 4 +++- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/modules/cockpit/pages/getting-started.adoc b/docs/modules/cockpit/pages/getting-started.adoc index 8ad991a5..1efb6455 100644 --- a/docs/modules/cockpit/pages/getting-started.adoc +++ b/docs/modules/cockpit/pages/getting-started.adoc @@ -3,7 +3,7 @@ This guide installs Cockpit with Helm and runs a first Trino query. You need an existing PostgreSQL database, an OIDC client for Cockpit, a Trino cluster, the Stackable Secret Operator and an Ingress or reverse proxy that serves `https://cockpit.example.com`. -Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/oauth2/callback/oidc`, see xref:installation/authentication.adoc[]. +Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/callback/oidc`, see xref:installation/authentication.adoc[]. Create a Secret with the database password and the OIDC client secret: @@ -35,7 +35,7 @@ database: tls: secretClass: tls # <2> trino: - url: https://trino-coordinator:8443 + url: https://trino-coordinator-default-headless:8443 tls: secretClass: tls # <3> ---- diff --git a/docs/modules/cockpit/pages/installation/authentication.adoc b/docs/modules/cockpit/pages/installation/authentication.adoc index 94ba18da..c127166f 100644 --- a/docs/modules/cockpit/pages/installation/authentication.adoc +++ b/docs/modules/cockpit/pages/installation/authentication.adoc @@ -2,7 +2,7 @@ :description: Configure login to Stackable Cockpit with any OpenID Connect provider, such as Keycloak, including callback URL, scopes and session secret. Users log in to Cockpit through an OpenID Connect (OIDC) provider, for example Keycloak. -Register a confidential client for Cockpit with the redirect URI `/api/auth/oauth2/callback/oidc`. +Register a confidential client for Cockpit with the redirect URI `/api/auth/callback/oidc`. [source,yaml] ---- diff --git a/docs/modules/cockpit/pages/modules/trino.adoc b/docs/modules/cockpit/pages/modules/trino.adoc index c6b88f8c..cfeae849 100644 --- a/docs/modules/cockpit/pages/modules/trino.adoc +++ b/docs/modules/cockpit/pages/modules/trino.adoc @@ -10,7 +10,7 @@ Set `trino.url` to connect all users to one Trino cluster: [source,yaml] ---- trino: - url: https://trino-coordinator:8443 # <1> + url: https://trino-coordinator-default-headless:8443 # <1> publicUrl: https://trino.example.com # <2> auth: type: basic # <3> @@ -23,6 +23,8 @@ trino: secretClass: tls # <4> ---- <1> The coordinator as Cockpit reaches it. +With `secretClass`, use the headless Service of the role group (`-coordinator--headless`), which the certificate covers. +From another namespace, append `..svc.cluster.local`. <2> Optional. The URL for links to the Trino web UI, defaults to `url`. <3> `none` (default) or `basic`. Cockpit does not start with `basic` and no username or password. <4> Provides the CA certificate of Trino. Alternatively set `caCert` to a mounted file, or `insecure: true` to skip verification. From 7921eb09904166caaa59174be0093adba52840fa Mon Sep 17 00:00:00 2001 From: Johannes Fleck Date: Mon, 9 Nov 2026 14:10:16 +0100 Subject: [PATCH 13/13] docs(helm): Document the proxy buffer size for large response headers --- .../cockpit/pages/installation/helm.adoc | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/modules/cockpit/pages/installation/helm.adoc b/docs/modules/cockpit/pages/installation/helm.adoc index e1d1b39e..ff9b8784 100644 --- a/docs/modules/cockpit/pages/installation/helm.adoc +++ b/docs/modules/cockpit/pages/installation/helm.adoc @@ -32,6 +32,26 @@ proxy: hostHeader: x-forwarded-host ---- +=== Response header size + +Pages send a `Link` header that preloads their JavaScript and CSS. +It grows with the number of files a page loads and exceeds 4 KB on some pages. +Proxies with a smaller header buffer answer these pages with `502 Bad Gateway`, for example ingress-nginx and nginx with their default `4k` buffer. +Raise the buffer to 16 KB: + +[source,yaml] +---- +ingress: + enabled: true + className: nginx + annotations: + nginx.ingress.kubernetes.io/proxy-buffer-size: "16k" +---- + +For plain nginx, set `proxy_buffer_size 16k;` and `proxy_busy_buffers_size 16k;`. + +// TODO: Remove once Cockpit uses SvelteKit 3, which preloads with elements instead of a header, see https://github.com/sveltejs/kit/pull/15939. + == CA certificates For backends with a private CA, set either a SecretClass or the path of a mounted CA file: