docs: add docs for the HTTP server (#1271)

* docs: add docs for the HTTP server

* docs: minor polish

* docs: add more explanation to the internal API.

Author: georgeh0

docs/docs/http_server.mdx

@@ -0,0 +1,82 @@
+---
+title: HTTP Server
+description: Run the built-in HTTP server for CocoInsight and health check
+---
+
+## Start the server
+
+There are two ways to start the server:
+
+### CLI
+
+Use the `cocoindex server` command. See more options in the [CLI](./core/cli).
+
+- Default bind address: **127.0.0.1:49344** (only exposed locally for safety)
+- Override if you need to expose to all IPs (example: `0.0.0.0:49344`)
+
+```bash
+# Start on the default local address (127.0.0.1:49344)
+cocoindex server path/to/app.py
+
+# Expose to all interfaces and allow CocoInsight
+cocoindex server path/to/app.py -a 0.0.0.0:49344 -ci
+
+# Add a custom CORS origin or allow a local frontend port
+cocoindex server path/to/app.py \
+  -c https://example.com \
+  -cl 3000
+```
+
+Flags of interest:
+
+- `-a`, `--address <IP:PORT>`: Bind address (defaults to 127.0.0.1:49344)
+- `-ci`, `--cors-cocoindex`: Allow `https://cocoindex.io` (CocoInsight) to access the server
+- `-c`, `--cors-origin <ORIGINS>`: Comma-separated list of allowed origins
+- `-cl`, `--cors-local <PORT>`: Allow `http://localhost:<PORT>`
+- `-L`, `--live-update`: Enable live updates while the server is running
+
+### Python API
+
+You can also start the server programmatically via the API.
+
+```python
+from cocoindex import start_server, settings
+
+server_settings = settings.ServerSettings(
+    # Default: "127.0.0.1:49344" — local only for safety
+    address="127.0.0.1:49344",
+    # Allow CocoInsight front-end
+    cors_origins=["https://cocoindex.io"],
+)
+
+start_server(server_settings)
+```
+
+To expose to all IPs:
+
+```python
+server_settings = settings.ServerSettings(
+    address="0.0.0.0:49344",
+)
+start_server(server_settings)
+```
+
+## What the server provides today
+
+- **CocoInsight access**: Enable with CLI `-ci`, or by API set `ServerSettings.cors_origins` to `"https://cocoindex.io"`. Then open `https://cocoindex.io/cocoinsight` and point it to your server address.
+  It'll talk to CocoIndex internal REST APIs exposed through `/cocoindex/api`.
+  The internal API is mainly designed for CocoInsight to use today, is subject to change and not considered as stable.
+
+- **Live updates from the CLI**: When running with `-L`, the server performs live updates while it’s up.
+  It's doing same thing as `cocoindex update -L` while the HTTP server is running.
+
+- **Health check**: `GET /healthz` responds with `application/json`:
+
+  - `status`: always `"ok"` when healthy
+  - `version`: the build-time package version (e.g., `"0.3.5"`)
+
+  Example response:
+
+  ```json
+  {"status":"ok","version":"0.3.5"}
+  ```

docs/sidebars.ts

@@ -83,6 +83,11 @@ const sidebars: SidebarsConfig = {
         'ai/llm',
       ],
     },
+    {
+      type: 'doc',
+      id: 'http_server',
+      label: 'HTTP Server',
+    },
     {
       type: 'doc',
       id: 'query',