adding MDX support and starting docs

.github/licenserc.yaml

@@ -27,4 +27,6 @@ header:
   paths-ignore:
     - '**/go.mod'
     - '**/go.sum'
-    - '**/*.json'
+    - '**/*.json'
+    - '**/**/*.md'
+    - '**/**/*.mdx'

webui/mdx-components.tsx

@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { MDXComponents } from "mdx/types";
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+    return {
+        ...components,
+    };
+}

webui/next.config.mjs

@@ -18,6 +18,7 @@
  */
 
 import { PHASE_DEVELOPMENT_SERVER } from "next/constants.js";
+import createMDX from "@next/mdx";
 
 const apiPrefix = "/api/v1";
 const devHost = "127.0.0.1:9379";
@@ -27,16 +28,22 @@ const nextConfig = (phase, { defaultConfig }) => {
     const isDev = phase === PHASE_DEVELOPMENT_SERVER;
     const host = isDev ? devHost : prodHost;
 
-    return {
-        async rewrites() {
+    const config = {
+        ...defaultConfig,
+        pageExtensions: ["js", "jsx", "md", "mdx", "ts", "tsx"],
+        rewrites: () => {
             return [
                 {
                     source: `${apiPrefix}/:slug*`,
                     destination: `http://${host}${apiPrefix}/:slug*`,
                 },
             ];
         },
+        experimental: {
+            mdxRs: true,
+        },
     };
+    return createMDX({})(config);
 };
 
 export default nextConfig;

webui/package.json

@@ -15,16 +15,21 @@
         "@fortawesome/free-brands-svg-icons": "^6.6.0",
         "@fortawesome/free-solid-svg-icons": "^6.6.0",
         "@fortawesome/react-fontawesome": "^0.2.2",
+        "@mdx-js/loader": "^3.1.0",
+        "@mdx-js/react": "^3.1.0",
         "@mui/icons-material": "^5.15.7",
         "@mui/material": "^5.15.5",
+        "@next/mdx": "^15.2.3",
         "@types/js-yaml": "^4.0.9",
+        "@types/mdx": "^2.0.13",
         "axios": "^1.6.7",
         "js-yaml": "^4.1.0",
         "next": "14.1.0",
         "react": "^18",
         "react-dom": "^18"
     },
     "devDependencies": {
+        "@tailwindcss/typography": "^0.5.16",
         "@types/node": "^20",
         "@types/react": "^18",
         "@types/react-dom": "^18",

webui/src/app/ui/banner.tsx

@@ -39,9 +39,8 @@ const links = [
         title: "Namespaces",
     },
     {
-        url: "https://kvrocks.apache.org",
-        title: "Documentation",
-        _blank: true,
+        url: "/docs/getting-started",
+        title: "Docs",
     },
 ];
 

webui/src/pages/docs/getting-started.mdx

@@ -0,0 +1,131 @@
+import MdxLayout from "../mdx-layout";
+
+# Apache Kvrocks Controller
+
+[![Build Status](https://github.com/apache/kvrocks-controller/workflows/CI%20Actions/badge.svg)](https://github.com/apache/kvrocks-controller/actions) [![Go Report Card](https://goreportcard.com/badge/github.com/apache/kvrocks-controller)](https://goreportcard.com/report/github.com/apache/kvrocks-controller) [![codecov](https://codecov.io/gh/apache/kvrocks-controller/branch/unsteable/graph/badge.svg?token=EKU6KU5IWK)](https://codecov.io/gh/apache/kvrocks-controller)
+
+Apache Kvrocks Controller is a cluster management tool for [Apache Kvrocks](https://github.com/apache/incubator-kvrocks), including the following key features:
+
+- Failover - controller will failover or remove the master/slave node when probing failed
+- Scale out the cluster in one line command
+- Manage many clusters in one controller cluster
+- Support multi metadata storages like etcd and so on
+
+## Building and Running
+
+### Build binaries
+
+```shell
+$ git clone https://github.com/apache/kvrocks-controller
+$ cd kvrocks-controller
+$ make # You can find the binary file in the `_build` dir if all goes good
+```
+
+### Overview
+
+![image](/docs/overview.png)
+For the storage, the ETCD is used as the default storage now. Welcome to contribute other storages like MySQL, Redis, Consul and so on. And what you need to do is to implement the [Engine interface](https://github.com/apache/kvrocks-controller/blob/unstable/store/engine/engine.go).
+
+### Supported Storage Engine
+
+- ETCD
+- Zookeeper
+- Consul by HashiCorp
+- Embedded Raft storage (experimental)
+
+### Run the controller server
+
+```shell
+# Use docker-compose to setup the etcd or zookeeper
+$ make setup
+# Run the controller server
+$ ./_build/kvctl-server -c config/config.yaml
+```
+
+### Run the controller server in Docker
+
+```shell
+$ docker run -it -p 9379:9379 apache/kvrocks-controller:latest
+```
+
+![image](/docs/server.gif)
+
+### Run server with the embedded Raft engine
+
+> Note: The embedded Raft engine is still in the experimental stage, and it's not recommended to use it in the production environment.
+
+Change the storage type to `raft` in the configuration file.
+
+```yaml
+storage_type: raft
+
+raft:
+    id: 1
+    data_dir: "/data/kvrocks/raft/1"
+    cluster_state: "new"
+    peers:
+        - "http://127.0.0.1:6001"
+        - "http://127.0.0.1:6002"
+        - "http://127.0.0.1:6003"
+```
+
+- `id`: the id for the raft node, it's also an index in the `peers` list
+- `data_dir`: the directory to store the raft data
+- `cluster_state`: the state of the raft cluster, it should be `new` when the cluster is initialized. And it should be `existing` when the cluster is already bootstrapped.
+- `peers`: the list of the raft peers, it should include all the nodes in the cluster.
+
+And then you can run the controller server with the configuration file.
+
+```shell
+$ ./_build/kvctl-server -c config/config-raft.yaml
+```
+
+#### Add/Remove a raft peer node
+
+We now support adding and removing via the HTTP API.
+
+```shell
+# Add a new peer node
+curl -XPOST -d '{"id":4,"peer":"http://127.0.0.1:6004","operation":"add"}'  http://127.0.0.1:9379/api/v1/raft/peers
+
+# Remove a peer node
+curl -XPOST -d '{"id":4, "operation":"remove"}'  http://127.0.0.1:9379/api/v1/raft/peers
+
+# List all the peer nodes
+curl http://127.0.0.1:9379/api/v1/raft/peers
+```
+
+### Use client to interact with the controller server
+
+```shell
+# Show help
+$ ./_build/kvctl --help
+
+# Create namespace
+$ ./_build/kvctl create namespace test-ns
+
+# List namespaces
+$ ./_build/kvctl list namespaces
+
+# Create cluster in the namespace
+$ ./_build/kvctl create cluster test-cluster --nodes 127.0.0.1:6666,127.0.0.1:6667 -n test-ns
+
+# List clusters in the namespace
+$ ./_build/kvctl list clusters -n test-ns
+
+# Get cluster in the namespace
+$ ./_build/kvctl get cluster test-cluster -n test-ns
+
+# Migrate slot from source to target
+$ ./_build/kvctl migrate slot 123 --target 1 -n test-ns -c test-cluster
+```
+
+For the HTTP API, you can find the [HTTP API(work in progress)](docs/API.md) for more details.
+
+## License
+
+Licensed under the [Apache License, Version 2.0](LICENSE)
+
+export default function MDXPage({ children }) {
+    return <MdxLayout>{children}</MdxLayout>;
+}

webui/src/pages/docs/supported-commands.mdx

@@ -0,0 +1 @@
+# Supported Commands

webui/src/pages/mdx-layout.tsx

@@ -0,0 +1,22 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export default function MdxLayout({ children }: { children: React.ReactNode }) {
+    return <div>{children}</div>;
+}