From b79b068568e5dd2a766c0c6a5cf4ab46c437599d Mon Sep 17 00:00:00 2001 From: Shubham Padia Date: Thu, 11 Sep 2025 15:03:45 +0000 Subject: [PATCH] help: Add --only-help-center to run-dev. The astro dev server takes a lot of memory and is disabled by default in `run-dev`. We add another option to only run the dev server which is the recommended mode for development. We still keep around the `--help-center-dev-server` mode for folks who have machines with higher specifications. See https://chat.zulip.org/#narrow/channel/19-documentation/topic/edits.20not.20appearing.20with.20vagrant/near/2256856 --- templates/zerver/development/dev_tools.html | 74 +++++++++------------ tools/run-dev | 24 ++++++- 2 files changed, 52 insertions(+), 46 deletions(-) diff --git a/templates/zerver/development/dev_tools.html b/templates/zerver/development/dev_tools.html index 7d744a1dac..3787e5f43a 100644 --- a/templates/zerver/development/dev_tools.html +++ b/templates/zerver/development/dev_tools.html @@ -137,51 +137,39 @@ -

Development instructions for help center (Beta)

+

Development instructions for help center

- These commands are to run the project for an ongoing migration for our help center docs to use - @astrojs/starlight. You can track the - progress for the project at #30450. + Running ./tools/run-dev without any flags will not run the help center at all. + The development server for the help center takes significant resources to run and we don't + want to increase the minimum requirements to run Zulip for development. +

+

Dev server (supports hot reload but not search)

+

+ This mode is useful when you are editing a help center file, and want to visualize the changes + quickly in the help center documentation. +

+

+ ./tools/run-dev --only-help-center will run a dev server at + /help that supports hot reload. Note that, with this flag, search will not work + in the help center docs. In this mode, the Zulip web app and other related services will not run. + Since the dev server consumes a significant amount of memory, this is the recommended way to run + the dev server for the help center. +

+

+ If you have a machine with resources significantly more than minimum requirements to run Zulip in + development, you can choose to run the dev server alongside Zulip using + ./tools/run-dev --help-center-dev-server. + The dev server makes a bunch of request to base Zulip URL instead of scoping it to the astro/starlight + base url. For this reason, in this mode, we run the dev server on it's own port and redirect help center + requests to the appropriate port (9995 by default). +

+

Serve static build (supports search but not hot reload)

+

+ Please run ./tools/build-help-center to generate a static build of the help center. + ./tools/run-dev --help-center will host the generated build on + /help. Note that you need to generate a build and pass the flag mentioned for the search + to work.

- diff --git a/tools/run-dev b/tools/run-dev index cbe186951e..e7a9976926 100755 --- a/tools/run-dev +++ b/tools/run-dev @@ -71,7 +71,12 @@ parser.add_argument( parser.add_argument( "--help-center-dev-server", action="store_true", - help="Run dev server for help center. Hot reload will work for this mode, but search will not work in the generated website.", + help="Run dev server for help center alongside the Zulip app. Hot reload will work for this mode, but search will not work in the generated website.", +) +parser.add_argument( + "--only-help-center", + action="store_true", + help="Run help center dev server on port 9991 without running the Zulip web app and related services", ) add_provision_check_override_param(parser) options = parser.parse_args() @@ -294,13 +299,15 @@ async def forward(upstream_port: int, request: web.Request) -> web.StreamRespons return response -def run_help_center_dev_server(external_host: str) -> "subprocess.Popen[bytes]": +def run_help_center_dev_server( + external_host: str, port: int = help_center_port +) -> "subprocess.Popen[bytes]": return subprocess.Popen( [ "/usr/local/bin/corepack", "pnpm", "dev", - f"--port={help_center_port}", + f"--port={port}", "--host", f"--allowed-hosts={urlsplit(external_host).hostname}", ], @@ -368,6 +375,12 @@ build step and rerun `run-dev`.""") def print_listeners(external_host_url: str) -> None: + if options.only_help_center: + print( + f"\n{CYAN}Help center dev server running on:{ENDC} {external_host_url}/help\nZulip web app and other related services will not run in this mode." + ) + return + print(f"\nStarting Zulip on:\n\n\t{CYAN}{external_host_url}/{ENDC}\n\nInternal ports:") ports = [ (proxy_port, "Development server proxy (connect here)"), @@ -432,6 +445,11 @@ async def serve() -> None: http_protocol = "https" if options.behind_https_proxy else "http" external_host_url = f"{http_protocol}://{external_host}" + if options.only_help_center: + children.append(run_help_center_dev_server(external_host_url, proxy_port)) + print_listeners(external_host_url) + return + if options.test: do_one_time_webpack_compile() else: