add command-line options for Uvicorn server configuration

app/main.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import argparse
 import asyncio
 import json
 import re
@@ -387,8 +388,51 @@ def _safe_data_file(path_value: str, root: Path) -> Path | None:
     return None
 
 
-def run() -> None:
-    uvicorn.run("app.main:app", host=settings.host, port=settings.port, reload=False)
+def _positive_integer(value: str) -> int:
+    try:
+        number = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("must be a whole number") from error
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return number
+
+
+def _port_number(value: str) -> int:
+    port = _positive_integer(value)
+    if port > 65_535:
+        raise argparse.ArgumentTypeError("must be between 1 and 65535")
+    return port
+
+
+def _parse_server_arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run the SiteHarbor FastAPI server with Uvicorn.")
+    parser.add_argument(
+        "--port",
+        type=_port_number,
+        default=settings.port,
+        metavar="PORT",
+        help=f"bind port (default: SITEHARBOR_PORT or {settings.port})",
+    )
+    parser.add_argument(
+        "--workers",
+        type=_positive_integer,
+        default=1,
+        metavar="WORKERS",
+        help="number of Uvicorn worker processes (default: 1)",
+    )
+    return parser.parse_args(argv)
+
+
+def run(argv: list[str] | None = None) -> None:
+    arguments = _parse_server_arguments(argv)
+    uvicorn.run(
+        "app.main:app",
+        host=settings.host,
+        port=arguments.port,
+        workers=arguments.workers,
+        reload=False,
+    )
 
 
 if __name__ == "__main__":