First docs draft

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

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[]

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='<database password>' \
+  --from-literal=oidc-client-secret='<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`.

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.

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 `<base URL>/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.

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

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.

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

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.

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.

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