feat(docs): getting logos together

Author: grampelberg

README.md

@@ -1,4 +1,7 @@
-# kty
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./docs/public/logo-dark-github.gif">
+  <img alt="logo" src="./docs/public/logo-light-github.gif">
+</picture>
 
 The terminal for Kubernetes. kty is the easiest way to access resources such as
 pods on your cluster - all without `kubectl`. Once kty is installed on your

docs/.prettierrc.yaml

@@ -0,0 +1,6 @@
+# @format
+
+semi: false
+singleQuote: true
+proseWrap: always
+parser: mdx

docs/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/pages/building-your-application/configuring/typescript for more information.

docs/package.json

@@ -19,15 +19,19 @@
   },
   "homepage": "https://github.com/grampelberg/kty#readme",
   "dependencies": {
-    "next": "^13.0.6",
-    "nextra": "latest",
-    "nextra-logo": "^0.1.3-beta.1",
-    "nextra-theme-docs": "latest",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "@theguild/remark-mermaid": "^0.1.2",
+    "next": "^14.2.9",
+    "nextra": "alpha",
+    "nextra-theme-docs": "alpha",
+    "posthog-js": "^1.161.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@types/node": "18.11.10",
-    "typescript": "^4.9.3"
+    "@types/node": "^22.5.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.45",
+    "tailwindcss": "^3.4.11",
+    "typescript": "^5.6.2"
   }
 }

docs/pages/_app.tsx

@@ -0,0 +1,36 @@
+import '../styles/globals.css'
+
+import React, { useEffect } from 'react'
+import { useRouter } from 'next/router'
+
+import posthog from 'posthog-js'
+import { PostHogProvider } from 'posthog-js/react'
+
+if (typeof window !== 'undefined' && process.env.NEXT_PUBLIC_POSTHOG) {
+  posthog.init(process.env.NEXT_PUBLIC_POSTHOG, {
+    api_host: 'https://us.i.posthog.com',
+    loaded: (posthog) => {
+      if (process.env.NODE_ENV === 'development') posthog.debug()
+    },
+  })
+}
+
+export default function App({ Component, pageProps }) {
+  const router = useRouter()
+
+  useEffect(() => {
+    // Track page views
+    const handleRouteChange = () => posthog?.capture('$pageview')
+    router.events.on('routeChangeComplete', handleRouteChange)
+
+    return () => {
+      router.events.off('routeChangeComplete', handleRouteChange)
+    }
+  }, [])
+
+  return (
+    <PostHogProvider client={posthog}>
+      <Component {...pageProps} />
+    </PostHogProvider>
+  )
+}

docs/pages/_meta.js

@@ -1,5 +1,15 @@
 export default {
-  index: 'Overview',
+  '*': {
+    theme: {
+      breadcrumb: false,
+    },
+  },
+  index: {
+    title: 'Overview',
+    display: 'hidden',
+  },
+  'getting-started': 'Getting Started',
+  architecture: 'Architecture',
   legal: {
     title: 'Legal',
     display: 'hidden',

docs/pages/architecture/_meta.js

@@ -0,0 +1 @@
+export default {}

docs/pages/auth.mdx docs/pages/architecture/access-control.mdx

@@ -1,4 +1,4 @@
-# Authentication and Authorization
+# Access Control
 
 kty utilizes external systems for both authn and authz. To fetch your identity,
 a combo of OpenID and the `keys` resource in your cluster are used. These map
@@ -38,7 +38,7 @@ flowchart TD
     style conn fill:none,stroke:none
 ```
 
-## Identity (Authentication)
+## Authentication
 
 There are two ways for an incoming SSH session to get a user identity:
 

docs/pages/getting-started.mdx

@@ -43,10 +43,10 @@ From this point, here's a few suggestions for things to check out:
   scp -P 2222 me@localhost:/default/my-pod/etc/hosts /tmp
   ```
 
-- Use your own [OpenID provider](docs/deployment.md#bring-your-own-provider).
+- Use your own [OpenID provider](/installation#bring-your-own-provider).
 
 Note: you'll want to install on-cluster to use the tunnelling functionality.
-Check out the [helm](docs/deployment.md#helm) docs for a quick way to do that.
+Check out the [helm](/installation/helm) docs for a quick way to do that.
 
 [cli-download]: https://github.com/grampelberg/kty/releases
 [k3d]: https://k3d.io

docs/pages/deployment.mdx docs/pages/installation.mdx

@@ -1,18 +1,24 @@
-# Deployment
+import { Callout } from 'nextra/components'
 
-The `kty` server needs access to your cluster's API server and credentials to
-connect to it. There are a couple ways to do this:
+# Installation
+
+You can install kty anywhere that has access to your cluster's API server and
+credentials to connect to it. The easiest way to do this is by running it
+on-cluster and exposing the server via a load balancer.
 
 - [On cluster](#on-cluster)
 - [Off cluster](#off-cluster)
 
 [gateway-api]: https://gateway-api.sigs.k8s.io
-[helm-chart]: #helm
 [sa-plugin]:
   https://github.com/superbrothers/kubectl-view-serviceaccount-kubeconfig-plugin
-[helm-rbac]: helm/templates/rbac.yaml
+[helm-rbac]:
+  https://github.com/grampelberg/kty/blob/main/helm/templates/rbac.yaml
+[helm-chart]: /installation/helm
+
+## Configuration
 
-## Features
+### Features
 
 All the functionality is controlled via feature flags in the server:
 
@@ -23,7 +29,7 @@ All the functionality is controlled via feature flags in the server:
 - `egress-tunnel` - Provides `ssh -R` forwarding from the cluster to a local
   port.
 
-## Bring Your Own Provider
+### Bring Your Own Provider
 
 By default, kty provides Github and Google authentication via. [auth0][auth0].
 To get your own setup using auth0, check out their [instructions][auth0-setup].
@@ -50,37 +56,16 @@ using helm, there are some things to be aware of:
   using the [gateway api][gateway-api] or configuring your ingress controller to
   route TCP.
 
-Note: if you're debugging something, instead of setting global verbosity with
-`-vv`, use `RUST_LOG=none,kty=debug`. That'll keep other crates that are
-especially noisy out of the output.
-
-### Helm
-
-There is a provided `getting-started.yaml` set of values. To install this on
-your cluster, you can run:
-
-```bash
-helm install kty oci://ghcr.io/grampelberg/helm/kty \
-  -n kty --create-namespace \
-  --version $(curl -L https://api.github.com/repos/grampelberg/kty/tags | jq -r '.[0].name' | cut -c2-) \
-  -f https://raw.githubusercontent.com/grampelberg/kty/main/helm/getting-started.yaml
-```
-
-Note: this exposes the kty service externally by default. To get that IP
-address, you can run:
-
-```bash
-kubectl -n kty get service server --output=jsonpath='{.status.loadBalancer.ingress[0].ip}'
-```
-
-For more detailed instructions, take a look at the [README][helm-readme].
-
-[helm-readme]: helm/README.md
+<Callout type="info">
+  If you're debugging something, instead of setting global verbosity with `-vv`,
+  use `RUST_LOG=none,kty=debug`. That'll keep other crates that are especially
+  noisy out of the output.
+</Callout>
 
 ## Off-Cluster
 
-If you're already using jump hosts to get into your cluster, kty can run there.
-Here are some things to be aware of:
+If you're already using jump hosts to get into your cluster, kty can run there
+as well. Here are some things to be aware of:
 
 - Provide credentials by creating a `kubeconfig` that uses the correct service
   account. here are [some plugins][sa-plugin] to make this easy. You'll still

docs/pages/installation/helm.mdx

@@ -0,0 +1,34 @@
+import { Callout } from 'nextra/components'
+
+# Helm
+
+There is a provided `getting-started.yaml` set of values. To install this on
+your cluster, you can run:
+
+```bash
+helm install kty oci://ghcr.io/grampelberg/helm/kty \
+  -n kty --create-namespace \
+  --version $(curl -L https://api.github.com/repos/grampelberg/kty/tags | jq -r '.[0].name' | cut -c2-) \
+  -f https://raw.githubusercontent.com/grampelberg/kty/main/helm/getting-started.yaml
+```
+
+Note: this exposes the kty service externally by default. To get that IP
+address, you can run:
+
+```bash
+kubectl -n kty get service server --output=jsonpath='{.status.loadBalancer.ingress[0].ip}'
+```
+
+See the [values.yaml][values.yaml] file for all possible configuration options.
+Some of the things that are configurable out of the box:
+
+- Autoscaling
+- OpenID provider
+- Ingress
+
+<Callout type="warning">
+  If you're trying to install directly from the repository, you'll need to set
+  `server.image` to the correct image as it will try and use a placeholder.
+</Callout>
+
+[values.yaml]: https://github.com/grampelberg/kty/blob/main/helm/values.yaml

docs/pages/metrics.mdx

@@ -0,0 +1,33 @@
+# Operations
+
+## Monitoring
+
+| Name | Description |
+| --- | --- |
+| `bytes_received_total` | Total number of bytes received. This should be keyboard input. |
+| `channel_bytes_sent_total` | Total number of bytes sent via a channel by IO type (blocking, non-blocking). This is what the UI and raw modes use to send data to the client. It will be different that the amount of bytes `russh` itself. |
+| `ssh_clients_total` | Number of incoming connections. |
+| `ssh_session_errors_total` | Number of non-IO related unhandled errors at the session level. |
+| `session_total` | Number of sessions created. |
+| `active_sessions` | Number of currently active sessions. |
+| `session_duration_minutes` | Duration of a session in minutes. |
+| `unexpected_state_total` | Number of times an unexpected state was encountered. This should only be incremented if there's a bug. |
+| `auth_attempts_total` | Number of authentication attempts by method (publickey, interactive). This can seem inflated because `publickey` will always be attempted first and `interactive` will happen at least twice for every success. `auth_results_total` |
+| `auth_attempts_total` | Number of auth responses returned by method and result (accept, partial, reject). Note that this can seem inflated because `publickey` is always attempted first and provides a rejection before moving onto other methods. |
+| `auth_succeeded_total` | Number of fully authn and authz'd users. After this, users can request a PTY. |
+| `code_generated_total` | Number of codes generated for users. This is the first half of the `interactive` mode. |
+| `code_checked_total` | Number of codes that have been checked by result (valid, invalid). This is the second half of the `interactive` mode and it is possible that users retry after getting `invalid` because of something on the openid provider side. |
+| `container_exec_duration_minutes` | Number of minutes a raw terminal was running exec'd into a pod. |
+| `table_filter_total` | Number of times a table was filtered. |
+| `widget_views_total` | Number of times a widget was created by resource (container, pod) and type (cmd, log, yaml, ...). |
+| `requests_total` | Number of requests that have come in by type (pty, sftp, window_resize). |
+| `sftp_active_sessions` | Total number of active sessions currently. |
+| `sftp_bytes_total` | Total number of bytes transferred via sftp by direction (read, write). |
+| `sftp_files_total` | Total number of files by direction (sent, received). |
+| `sftp_stat_total` | Total number of times `stat` was called on a path. |
+| `sftp_list_total` | Total number of times `list` was called on a path. |
+| `channels_total` | Total number of channel actions by method (open_session, direct_tcpip, ...). |
+| `stream_duration_seconds` | Number of seconds a stream was alive by resource and direction. |
+| `stream_bytes_total` | Number of bytes transfered by resource, direction and destination. |
+| `stream_total` | Total number of streams by resource and direction. |
+| `stream_active` | Currently active numberof streams by resource and direction. |

docs/pages/operations.mdx

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

docs/postcss.config.js

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

docs/public/ico-dark.png

@@ -0,0 +1,11 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './pages/**/*.{js,jsx,ts,tsx,md,mdx}',
+    './components/**/*.{js,jsx,ts,tsx,md,mdx}',
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}