From 899a030dabbcf9bdf361bbf0135e86ff4c898bf5 Mon Sep 17 00:00:00 2001 From: Jiangzhou He Date: Fri, 7 Nov 2025 09:39:49 -0800 Subject: [PATCH 1/3] docs: add docs for the HTTP server --- docs/docs/http_server.mdx | 79 +++++++++++++++++++++++++++++++++++++++ docs/sidebars.ts | 5 +++ 2 files changed, 84 insertions(+) create mode 100644 docs/docs/http_server.mdx diff --git a/docs/docs/http_server.mdx b/docs/docs/http_server.mdx new file mode 100644 index 00000000..63198e67 --- /dev/null +++ b/docs/docs/http_server.mdx @@ -0,0 +1,79 @@ +--- +title: HTTP Server +description: Run the built-in HTTP server to expose CocoIndex APIs +--- + +## 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 `: Bind address (defaults to 127.0.0.1:49344) +- `-ci`, `--cors-cocoindex`: Allow `https://cocoindex.io` (CocoInsight) to access the server +- `-c`, `--cors-origin `: Comma-separated list of allowed origins +- `-cl`, `--cors-local `: Allow `http://localhost:` +- `-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. + +- **Live updates from the CLI**: When running with `-L`, the server performs live updates while it’s up (similar to `cocoindex update -L`). + +- **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"} + ``` diff --git a/docs/sidebars.ts b/docs/sidebars.ts index e18fd139..09345938 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -83,6 +83,11 @@ const sidebars: SidebarsConfig = { 'ai/llm', ], }, + { + type: 'doc', + id: 'http_server', + label: 'HTTP Server', + }, { type: 'doc', id: 'query', From f214f7c9855a581236d98efb3a664de7d0c18c2e Mon Sep 17 00:00:00 2001 From: Jiangzhou He Date: Fri, 7 Nov 2025 09:42:27 -0800 Subject: [PATCH 2/3] docs: minor polish --- docs/docs/http_server.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/http_server.mdx b/docs/docs/http_server.mdx index 63198e67..c02d6b9d 100644 --- a/docs/docs/http_server.mdx +++ b/docs/docs/http_server.mdx @@ -1,6 +1,6 @@ --- title: HTTP Server -description: Run the built-in HTTP server to expose CocoIndex APIs +description: Run the built-in HTTP server for CocoInsight and health check --- ## Start the server @@ -65,7 +65,8 @@ start_server(server_settings) - **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. -- **Live updates from the CLI**: When running with `-L`, the server performs live updates while it’s up (similar to `cocoindex update -L`). +- **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`: From d7fc991ec9b4c72ede3c58abcb60a61f59cb66ea Mon Sep 17 00:00:00 2001 From: Jiangzhou He Date: Fri, 7 Nov 2025 09:44:41 -0800 Subject: [PATCH 3/3] docs: add more explanation to the internal API. --- docs/docs/http_server.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/http_server.mdx b/docs/docs/http_server.mdx index c02d6b9d..6165c601 100644 --- a/docs/docs/http_server.mdx +++ b/docs/docs/http_server.mdx @@ -64,6 +64,8 @@ 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.