paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 16:14:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

help: Add --only-help-center to run-dev.

Browse Source 
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
This commit is contained in:
Shubham Padia
2025-09-11 15:03:45 +00:00
committed by Tim Abbott
parent 8ddc7bee00
commit b79b068568
2 changed files with 52 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
templates/zerver/development/dev_tools.html
View File

@@ -137,51 +137,39 @@
</ul>
</li>
</ul>
<h2>Development instructions for help center (Beta)</h2>
<h2>Development instructions for help center</h2>
<p>
These commands are to run the project for an ongoing migration for our help center docs to use
<a href="https://github.com/withastro/starlight">@astrojs/starlight</a>. You can track the
progress for the project at <a href="https://github.com/zulip/zulip/issues/30450">#30450</a>.
Running <code>./tools/run-dev</code> 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.
</p>
<ul>
<li>
<code>./tools/build-help-center</code> will convert the existing help center MD files to MDX,
and create a production build for the converted MDX files.
<ul>
<li>
You can run <code>./tools/convert-help-center-docs-to-mdx</code> to convert the help
center MD files without the build step; see running a dev server that supports hot
reload below.
</li>
<li>
You can run <code>pnpm build</code> within the <code>starlight_help</code> directory to run
the build step separately.
</li>
</ul>
</li>
<li>
<code>./tools/run-dev --help-center</code> will host the generated build on
<code>/help</code>. Note that search will work in the beta help center docs with
this flag. For testing changes related to the migration of the help center docs, using the tool
to build the beta help center docs and running the dev server with this flag should be fine.
</li>
<li>
<code>./tools/run-dev --help-center-dev-server</code> will run a dev server at
<h3> Dev server (supports hot reload but not search)</h3>
<p>
This mode is useful when you are editing a help center file, and want to visualize the changes
quickly in the help center documentation.
</p>
<p>
<code>./tools/run-dev --only-help-center</code> will run a dev server at
<code>/help</code> that supports hot reload. Note that, with this flag, search will not work
in the beta help center docs. This mode is useful when you are editing a help center file, and
want to visualize the changes quickly in the beta help center documentation. You will need the
converted MDX files to be already generated through
<code>./tools/convert-help-center-docs-to-mdx</code> before you run the dev server with this flag.
<ul>
<li>
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.
</p>
<p>
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
<code>./tools/run-dev --help-center-dev-server</code>.
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, we run the dev server on it's own port and redirect help center requests to
the appropriate port (9995 by default).
</li>
</ul>
</li>
</ul>
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).
</p>
<h3> Serve static build (supports search but not hot reload)</h3>
<p>
Please run <code>./tools/build-help-center</code> to generate a static build of the help center.
<code>./tools/run-dev --help-center</code> will host the generated build on
<code>/help</code>. Note that you need to generate a build and pass the flag mentioned for the search
to work.
</p>
</div>
</div>

24
tools/run-dev
View File

@@ -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: