Add docs by Bohreromir · Pull Request #422 · stackabletech/cockpit

Bohreromir · 2026-10-28T13:50:19Z

Description

Warning

This adds the docs to this repo only. Integration into the docs is in here: stackable-utils#133

Docs

Release note

Checklist

Author

AI review done, findings addressed
Tests added or updated
Changelog updated (if the repo keeps one)

Reviewer

Useful comments and logging
Docs added or updated per the style guide

Acceptance

Check for release notes and docs

github-actions · 2026-10-28T13:52:26Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	67.49%	9183 / 13605
🔵	Statements	66.45%	12363 / 18604
🔵	Functions	68.27%	2965 / 4343
🔵	Branches	57.42%	5177 / 9015

File Coverage

No changed files found.

Generated in workflow #1267 for commit e7de79d by the Vitest Coverage Report Action

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.

…ark rules

Getting started also needs the Secret Operator for the SecretClasses and an Ingress or reverse proxy that serves Cockpit over HTTPS.

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.

Techassi

Just a few comments, as @lfrancke is reviewing this more thoroughly.

Techassi · 2026-11-09T14:53:13Z

+
+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.


Suggested change

* xref:modules/trino.adoc[Trino]: a SQL editor with code completion and a schema browser.

* xref:modules/trino.adoc[Trino]: an SQL editor with code completion and a schema browser.

Techassi · 2026-11-09T14:57:24Z

+
+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.
+


We should probably include a screenshot of the entrypoint of the Cockpit (most likely the dashboard with a few bookmarks).

Screenshots are so annoying to update...... but we should have at least one or two somewhere, not more in my opinion.

So what about a npm run docs:screenshots ;)
#456

Techassi · 2026-11-09T14:58:57Z

+
+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/callback/oidc`, see xref:installation/authentication.adoc[].


Suggested change

Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/callback/oidc`, see xref:installation/authentication.adoc[].

Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/callback/oidc`, see the xref:installation/authentication.adoc[authentication] page for more details.

lfrancke · 2026-11-10T07:37:50Z

@@ -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.


Can we phrase this a bit more "openly" so that it is still correct-ish when we add more components but forget to update the description?

lfrancke · 2026-11-10T07:39:59Z

+
+== Architecture
+
+Cockpit is a Node.js server that connects to Trino as the logged-in user and to S3 with the connections each user configures.


I'd say "Node.js server" is an implementation detail we can leave out. And I also don't think we need to say what goes into PostgreSQL. The code is available if needed. I'd just remove this entire section (Architecture). It's just going to drift.

lfrancke · 2026-11-10T07:51:02Z

+      name: cockpit
+  tls:
+    secretClass: tls # <2>
+trino:


Wasn't it also possible to connect to a Trino from inside Cockpit itself?

If so I think we should probably mention that this 1:1 connection is potentially only temporary.

Sure, both is possible at the moment. You can either set a fixed connection (might change that to an arbitrary number in the future) or have users connect them manually

lfrancke · 2026-11-10T07:53:19Z

@@ -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.


This list and the one below can just become outdated fast. I'd not name implementation specifics here.

lfrancke · 2026-11-10T08:38:16Z

+
+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.
+


Screenshots are so annoying to update...... but we should have at least one or two somewhere, not more in my opinion.

lfrancke · 2026-11-10T08:50:20Z

+    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`.


Suggested change

<2> Provides the CA certificate of PostgreSQL. Alternatively set `caCert` to a mounted file. Both require `verify-full`.

<2> Provides the CA certificate of PostgreSQL. Alternatively set `caCert` to a mounted file. `secretClass` and `caCert` both require `verify-full`.

lfrancke · 2026-11-10T08:51:13Z

+<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. 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.


Suggested change

Set it explicitly when deploying with `helm template` or Argo CD, which cannot read the existing Secret, otherwise every deployment logs out all users.

Set it explicitly when deploying with `helm template` or Argo CD. They cannot read the existing Secret, so every deployment would generate a new one and log out all users.

lfrancke · 2026-11-10T08:51:30Z

+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:


Suggested change

The module is disabled by default:

The module is disabled by default.

To enable it, set:

lfrancke · 2026-11-10T08:54:37Z

+: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, a Trino cluster, the Stackable Secret Operator and an Ingress or reverse proxy that serves `https://cockpit.example.com`.


Can we make this a bullet point list?

lfrancke · 2026-11-10T08:55:58Z

+|PostgreSQL host.
+
+|`DATABASE_PORT`
+|`31432`


This is probably a fix in the code but PostgreSQL defaults to 5432 and I think we should also default to that.

Yes, will do in another pr with the code chagnes

Bohreromir linked an issue Oct 28, 2026 that may be closed by this pull request

Documentation #378

Open

6 tasks

Bohreromir force-pushed the worktree-docs-antora branch from 56738af to d73ffdf Compare October 29, 2026 13:26

Bohreromir self-assigned this Oct 29, 2026

Bohreromir force-pushed the worktree-docs-antora branch from d73ffdf to 1df60d8 Compare October 30, 2026 10:54

feat(docs): first draft

eba1467

Bohreromir force-pushed the worktree-docs-antora branch from 1df60d8 to eba1467 Compare October 30, 2026 11:16

Bohreromir mentioned this pull request Oct 30, 2026

epic: First Release Cockpit #294

Open

11 of 17 tasks

docs: Version the docs with the SDP like the operators

6d08dfd

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.

Bohreromir force-pushed the worktree-docs-antora branch from 6b777fa to 6d08dfd Compare November 2, 2026 10:46

This was referenced Nov 2, 2026

feat: add cockpit to release process stackabletech/stackable-utils#133

Open

docs: Add the Cockpit docs stackabletech/documentation#973

Draft

Bohreromir added 10 commits November 2, 2026 13:04

docs: Install the published Helm chart

daccaea

style(docs): Use single quotes in antora.yml

51be4e3

docs: Fix bookmark key and database TLS in getting started

d3c5073

docs: Add the OIDC redirect URI to getting started

5b0e502

docs: Address review findings

5e41826

docs: Document startup validation, logging variables and global bookm…

5e1e5df

…ark rules

Merge branch 'main' into worktree-docs-antora

b55afdd

docs(trino): Document how Trino errors are shown

9968d84

docs(helm): Document that Cockpit must be served at the root path

d878b8e

docs: Name the generated session Secret and list all prerequisites

5feb5f8

Getting started also needs the Secret Operator for the SecretClasses and an Ingress or reverse proxy that serves Cockpit over HTTPS.

Bohreromir added this to Stackable Engineering Nov 4, 2026

Bohreromir moved this to Development: Waiting for Review in Stackable Engineering Nov 4, 2026

Bohreromir marked this pull request as ready for review November 4, 2026 10:58

Merge branch 'main' into worktree-docs-antora

95a2d7c

Bohreromir changed the title ~~First docs draft~~ Add docs Nov 4, 2026

Bohreromir added 2 commits November 9, 2026 12:39

docs: Fix the OIDC redirect URI and Trino URL in examples

6e046e8

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(helm): Document the proxy buffer size for large response headers

7921eb0

Techassi self-requested a review November 9, 2026 14:41

lfrancke moved this from Development: Waiting for Review to Development: In Review in Stackable Engineering Nov 9, 2026

Techassi reviewed Nov 10, 2026

View reviewed changes

lfrancke requested changes Nov 10, 2026

View reviewed changes

docs: pr feedback

4d8bbe3

Bohreromir added this pull request to stack #455 November 10, 2026 18:40

Bohreromir added 2 commits November 10, 2026 20:10

docs: Add a dashboard screenshot to the overview page

10d305a

Merge branch 'main' into worktree-docs-antora

e7de79d

Bohreromir requested a review from lfrancke November 10, 2026 19:23


		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/trino.adoc[Trino]: a SQL editor with code completion and a schema browser.
	* xref:modules/trino.adoc[Trino]: an SQL editor with code completion and a schema browser.


		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.

	Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/callback/oidc`, see xref:installation/authentication.adoc[].
	Register the OIDC client with the redirect URI `https://cockpit.example.com/api/auth/callback/oidc`, see the xref:installation/authentication.adoc[authentication] page for more details.

		@@ -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.


		== Architecture

		Cockpit is a Node.js server that connects to Trino as the logged-in user and to S3 with the connections each user configures.

		@@ -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.

	<2> Provides the CA certificate of PostgreSQL. Alternatively set `caCert` to a mounted file. Both require `verify-full`.
	<2> Provides the CA certificate of PostgreSQL. Alternatively set `caCert` to a mounted file. `secretClass` and `caCert` both require `verify-full`.

	Set it explicitly when deploying with `helm template` or Argo CD, which cannot read the existing Secret, otherwise every deployment logs out all users.
	Set it explicitly when deploying with `helm template` or Argo CD. They cannot read the existing Secret, so every deployment would generate a new one and log out all users.

	The module is disabled by default:
	The module is disabled by default.
	To enable it, set:

Conversation

Bohreromir commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Docs

Release note

Checklist

Author

Reviewer

Acceptance

Uh oh!

github-actions Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

Techassi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Bohreromir commented Oct 28, 2026 •

edited

Loading

github-actions Bot commented Oct 28, 2026 •

edited

Loading