Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

chore(dev): consolidate server scripts into restart_server.sh flags (#4953)

LearningCircuit0dad09e00649
diff --git a/examples/api_usage/http/README.md b/examples/api_usage/http/README.md
index 39fae6059c..6fe454a27d 100644
--- a/examples/api_usage/http/README.md
+++ b/examples/api_usage/http/README.md
@@ -108,10 +108,10 @@ services:
### Server Logs
```bash
# Monitor real-time progress
-tail -f /tmp/ldr_server.log
+tail -f /tmp/ldr_server_5000.log
# Check recent logs
-tail -20 /tmp/ldr_server.log
+tail -20 /tmp/ldr_server_5000.log
```
### Web Interface
@@ -138,7 +138,7 @@ bash scripts/dev/restart_server.sh
**❌ "Research failed"**
```bash
# Check server logs for details
-tail -f /tmp/ldr_server.log
+tail -f /tmp/ldr_server_5000.log
# Common issues:
# - Ollama not running or wrong URL
diff --git a/examples/api_usage/http/advanced/simple_http_example.py b/examples/api_usage/http/advanced/simple_http_example.py
index 9234cf8164..f7670cf7c7 100755
--- a/examples/api_usage/http/advanced/simple_http_example.py
+++ b/examples/api_usage/http/advanced/simple_http_example.py
@@ -75,9 +75,9 @@ def main():
print("⚠️ IMPORTANT NOTES:")
print(" • This script may take several minutes to complete")
print(" • Research progress can be monitored in the server logs")
- print(" • Server logs are available at: /tmp/ldr_server.log")
+ print(" • Server logs are available at: /tmp/ldr_server_5000.log")
print(
- " • Use 'tail -f /tmp/ldr_server.log' to monitor progress in real-time"
+ " • Use 'tail -f /tmp/ldr_server_5000.log' to monitor progress in real-time"
)
print(" • Results will be available at the URL shown when complete\n")
@@ -92,7 +92,7 @@ def main():
" • Option 2: bash scripts/dev/restart_server.sh (recommended)"
)
print(
- " • Note: restart_server.sh will kill existing server process"
+ " • Note: restart_server.sh stops only the instance on its target port"
)
sys.exit(1)
print("✅ Server is running")
@@ -103,7 +103,9 @@ def main():
print("\n📋 HOW TO START THE SERVER:")
print(" • Option 1: python -m local_deep_research.web.app")
print(" • Option 2: bash scripts/dev/restart_server.sh (recommended)")
- print(" • Note: restart_server.sh will kill existing server process")
+ print(
+ " • Note: restart_server.sh stops only the instance on its target port"
+ )
sys.exit(1)
# Create test user automatically
@@ -187,7 +189,9 @@ def main():
research_id = research_data["research_id"]
print("✅ Research started successfully!")
print(f"🆔 Research ID: {research_id}")
- print("📊 Monitor progress in server logs: tail -f /tmp/ldr_server.log")
+ print(
+ "📊 Monitor progress in server logs: tail -f /tmp/ldr_server_5000.log"
+ )
print(f"🌐 Results will be available at: {API_URL}/results/{research_id}\n")
# Poll for results
@@ -226,7 +230,7 @@ def main():
f"❌ Research failed: {status.get('error', 'Unknown error')}"
)
print(
- "📋 Check server logs for details: tail -f /tmp/ldr_server.log"
+ "📋 Check server logs for details: tail -f /tmp/ldr_server_5000.log"
)
sys.exit(1)
elif current_status in ["queued", "in_progress"]:
@@ -246,7 +250,7 @@ def main():
print("⏰ 3-minute timeout reached - research is still running")
print("💡 This is normal for complex research queries!")
print(f"📊 Check results later at: {API_URL}/results/{research_id}")
- print("📋 Monitor progress with: tail -f /tmp/ldr_server.log")
+ print("📋 Monitor progress with: tail -f /tmp/ldr_server_5000.log")
print(
"🔍 The script will still try to fetch results (may be incomplete)"
)
@@ -383,7 +387,7 @@ def main():
)
print("💡 This is normal for complex research queries!")
print(f"📊 Check results later at: {API_URL}/results/{research_id}")
- print("📋 Monitor progress with: tail -f /tmp/ldr_server.log")
+ print("📋 Monitor progress with: tail -f /tmp/ldr_server_5000.log")
print(
"🔍 The research is still running - results will be available when complete"
)
@@ -415,10 +419,12 @@ if __name__ == "__main__":
print("🚀 START THE SERVER:")
print(" • Option 1: python -m local_deep_research.web.app")
print(" • Option 2: bash scripts/dev/restart_server.sh (recommended)")
- print(" • Note: restart_server.sh will kill existing server process\n")
+ print(
+ " • Note: restart_server.sh stops only the instance on its target port\n"
+ )
print("📊 MONITORING:")
- print(" • Server logs: tail -f /tmp/ldr_server.log")
+ print(" • Server logs: tail -f /tmp/ldr_server_5000.log")
print(" • This script polls for up to 3 minutes")
print(" • If research takes longer, script shows where to check results\n")
diff --git a/scripts/dev/restart_server.sh b/scripts/dev/restart_server.sh
index 5b56ec0c36..71d4f42f51 100755
--- a/scripts/dev/restart_server.sh
+++ b/scripts/dev/restart_server.sh
@@ -1,5 +1,26 @@
#!/bin/bash
-# Script to restart the LDR server
+# Restart the LDR dev server.
+#
+# Usage:
+# scripts/dev/restart_server.sh [PORT] [--debug] [--tmp]
+#
+# PORT Optional port (default: 5000). Passed via LDR_WEB_PORT.
+# --debug DEBUG logging (LDR_APP_DEBUG=true, LDR_LOG_SETTINGS=summary).
+# WARNING: debug logs may contain sensitive data (queries,
+# answers, API responses) — local dev / feature testing only,
+# never production or real user data.
+# --tmp Disposable instance: point LDR_DATA_DIR at a throwaway dir
+# (default /tmp/ldr-test) so encrypted user DBs, the auth DB,
+# library, logs, research_outputs etc. land OUTSIDE your real
+# data dir (~/.local/share/local-deep-research). Override the
+# location by exporting LDR_DATA_DIR before running. Reuses one
+# dir (doesn't accumulate throwaway databases). To start from a
+# clean slate, wipe LDR_DATA_DIR yourself first (e.g.
+# `rm -rf "$LDR_DATA_DIR"`) — this script never deletes data.
+#
+# Only the instance listening on the target PORT is stopped, so multiple
+# instances on different ports (e.g. several agents each on their own port)
+# coexist — restarting one does not kill the others.
#
# Referenced in:
# - tests/api_tests_with_login/README.md
@@ -7,30 +28,107 @@
# - examples/api_usage/http/advanced/simple_http_example.py
# Do not delete without updating those references.
-echo "Stopping existing LDR server..."
-pkill -f "python -m local_deep_research.web.app" 2>/dev/null || echo "No existing server found"
+set -u
+
+usage() {
+ cat <<'EOF'
+Restart the LDR dev server.
+
+Usage:
+ scripts/dev/restart_server.sh [PORT] [--debug] [--tmp]
+
+ PORT Optional port (default: 5000).
+ --debug DEBUG logging (may log sensitive data; local dev only).
+ --tmp Disposable instance: LDR_DATA_DIR -> /tmp/ldr-test (override by
+ exporting LDR_DATA_DIR). Keeps test data out of your real dir.
+ This script never deletes data; wipe LDR_DATA_DIR yourself to
+ start from a clean slate.
+ --test Alias for --tmp.
+
+Only the instance on the target PORT is stopped; instances on other ports
+keep running.
+EOF
+}
+
+PORT=5000
+debug=0
+use_tmp=0
+
+for arg in "$@"; do
+ case "$arg" in
+ --debug) debug=1 ;;
+ --tmp|--test) use_tmp=1 ;;
+ -h|--help) usage; exit 0 ;;
+ ''|*[!0-9]*) echo "Unknown argument: $arg" >&2; usage >&2; exit 2 ;;
+ *) PORT="$arg" ;;
+ esac
+done
+
+echo "Stopping existing LDR server on port ${PORT} (if any)..."
+# Port-scoped stop: kill only the process LISTENing on PORT, leaving
+# instances on other ports running. The port isn't in the process argv
+# (it comes from LDR_WEB_PORT), so a broad pkill can't distinguish them.
+if command -v fuser >/dev/null 2>&1; then
+ fuser -k "${PORT}/tcp" 2>/dev/null || echo "No existing server on port ${PORT}"
+elif command -v lsof >/dev/null 2>&1; then
+ pids=$(lsof -ti "tcp:${PORT}" -sTCP:LISTEN 2>/dev/null)
+ if [ -n "${pids}" ]; then
+ # $pids may be several PIDs; word-splitting is intended here.
+ # shellcheck disable=SC2086
+ kill ${pids} 2>/dev/null
+ else
+ echo "No existing server on port ${PORT}"
+ fi
+else
+ echo "Warning: neither fuser nor lsof found; cannot port-scope the stop." >&2
+ echo "Skipping stop to avoid killing instances on other ports." >&2
+fi
-# Wait a moment for the process to stop
sleep 1
-echo "Starting LDR server..."
-# Change to the script's parent directory (project root)
+# Change to the project root.
cd "$(dirname "$0")/../.." || exit 1
-# Start server in background and detach from terminal
-(nohup pdm run python -m local_deep_research.web.app > /tmp/ldr_server.log 2>&1 &) &
+# --- environment for the launched server -------------------------------------
+env_args=(LDR_WEB_PORT="${PORT}")
+
+if [ "$use_tmp" -eq 1 ]; then
+ : "${LDR_DATA_DIR:=/tmp/ldr-test}"
+ mkdir -p "$LDR_DATA_DIR"
+ echo "Using disposable LDR_DATA_DIR=$LDR_DATA_DIR"
+ env_args+=(LDR_DATA_DIR="${LDR_DATA_DIR}")
+fi
+
+if [ "$debug" -eq 1 ]; then
+ env_args+=(LDR_APP_DEBUG=true LDR_LOG_SETTINGS=summary)
+fi
+
+LOG_FILE="/tmp/ldr_server_${PORT}.log"
+
+if [ "$debug" -eq 1 ]; then
+ echo "Starting LDR server on port ${PORT} (DEBUG)..."
+else
+ echo "Starting LDR server on port ${PORT}..."
+fi
+# Start server in background and detach from terminal. Backgrounding nohup
+# directly (rather than wrapping in an extra `( ... & ) &` subshell) means
+# $! captures the real server PID, not a transient subshell that has already
+# exited. nohup ignores SIGHUP, so the server survives the launcher exiting
+# and is reparented to init.
+nohup env "${env_args[@]}" pdm run python -m local_deep_research.web.app > "${LOG_FILE}" 2>&1 &
SERVER_PID=$!
-# Give it a moment to start
sleep 2
-echo "Server started. PID: $SERVER_PID"
-echo "Logs: /tmp/ldr_server.log"
-echo "URL: http://127.0.0.1:5000"
+echo "Server started. PID: ${SERVER_PID}"
+echo "Logs: ${LOG_FILE}"
+echo "URL: http://127.0.0.1:${PORT}"
+if [ "$debug" -eq 1 ]; then
+ echo ""
+ echo "WARNING: DEBUG mode — logs may contain sensitive data; local dev only."
+fi
echo ""
-echo "To check server status: ps aux | grep 'python -m local_deep_research.web.app'"
-echo "To view logs: tail -f /tmp/ldr_server.log"
-echo "To stop server: pkill -f 'python -m local_deep_research.web.app'"
+echo "To view logs: tail -f ${LOG_FILE}"
+echo "To stop server: fuser -k ${PORT}/tcp"
-# Exit immediately - don't wait for background process
exit 0
diff --git a/scripts/dev/restart_server_debug.sh b/scripts/dev/restart_server_debug.sh
deleted file mode 100755
index a27fcee56d..0000000000
--- a/scripts/dev/restart_server_debug.sh
+++ /dev/null
@@ -1,40 +0,0 @@
-#!/bin/bash
-# Script to restart the LDR server with DEBUG logging enabled.
-# Do not remove — companion to restart_server.sh for debug workflows.
-#
-# WARNING: Debug logs may contain sensitive data (queries, answers, API responses).
-# This is for local development and feature testing only.
-# Do NOT use in production or with real user data.
-
-echo "Stopping existing LDR server..."
-pkill -f "python -m local_deep_research.web.app" 2>/dev/null || echo "No existing server found"
-
-# Wait a moment for the process to stop
-sleep 1
-
-echo "Starting LDR server in DEBUG mode..."
-# Change to the script's parent directory (project root)
-cd "$(dirname "$0")/../.." || exit 1
-
-# Start server in background and detach from terminal
-(nohup env LDR_APP_DEBUG=true LDR_LOG_SETTINGS=summary pdm run python -m local_deep_research.web.app > /tmp/ldr_server.log 2>&1 &) &
-SERVER_PID=$!
-
-# Give it a moment to start
-sleep 2
-
-echo "Server started. PID: $SERVER_PID"
-echo "Logs: /tmp/ldr_server.log"
-echo "URL: http://127.0.0.1:5000"
-echo ""
-echo "WARNING: Running in DEBUG mode (LDR_APP_DEBUG=true)"
-echo " - Debug logs may contain sensitive data (queries, answers, API responses)"
-echo " - For local development and feature testing only"
-echo " - Do NOT use in production or with real user data"
-echo ""
-echo "To check server status: ps aux | grep 'python -m local_deep_research.web.app'"
-echo "To view logs: tail -f /tmp/ldr_server.log"
-echo "To stop server: pkill -f 'python -m local_deep_research.web.app'"
-
-# Exit immediately - don't wait for background process
-exit 0
diff --git a/scripts/dev/run_test_instance.sh b/scripts/dev/run_test_instance.sh
deleted file mode 100755
index 1177ebbdc9..0000000000
--- a/scripts/dev/run_test_instance.sh
+++ /dev/null
@@ -1,64 +0,0 @@
-#!/bin/bash
-# Run a disposable test instance of the LDR dev server.
-#
-# Points LDR_DATA_DIR at a temp directory so encrypted user DBs, the auth
-# DB, library, logs, research_outputs etc. land outside your real data dir
-# (~/.local/share/local-deep-research) and can be wiped in one shot.
-
-set -eu
-
-usage() {
- cat <<'EOF'
-Run a disposable test instance of the LDR dev server.
-
-Points LDR_DATA_DIR at a temp directory so encrypted user DBs, the auth
-DB, library, logs, research_outputs etc. land outside your real data dir
-(~/.local/share/local-deep-research) and can be wiped in one shot.
-
-Usage:
- scripts/dev/run_test_instance.sh # start (existing test data kept)
- scripts/dev/run_test_instance.sh --reset # wipe the test data dir first
- scripts/dev/run_test_instance.sh --debug # start with DEBUG logging
-
---reset and --debug can be combined. Override the location
-(otherwise defaults to /tmp/ldr-test):
- LDR_DATA_DIR=$HOME/ldr-test scripts/dev/run_test_instance.sh
-EOF
-}
-
-reset=0
-restart=restart_server.sh
-for arg in "$@"; do
- case "$arg" in
- --reset) reset=1 ;;
- --debug) restart=restart_server_debug.sh ;;
- -h|--help) usage; exit 0 ;;
- *) echo "Unknown argument: $arg" >&2; usage >&2; exit 2 ;;
- esac
-done
-
-: "${LDR_DATA_DIR:=/tmp/ldr-test}"
-export LDR_DATA_DIR
-
-if [ "$reset" -eq 1 ]; then
- # Canonicalize first (-m so a not-yet-created dir still resolves) so a
- # symlinked or relative LDR_DATA_DIR can't slip a real location past the
- # guard, then refuse paths that obviously aren't a disposable test dir.
- # Keeps a misconfigured LDR_DATA_DIR from turning --reset into an
- # `rm -rf` of something real.
- real=$(realpath -m -- "$LDR_DATA_DIR")
- home=$(realpath -m -- "${HOME:-/nonexistent}")
- case "$real" in
- "/"|"$home"|"$home/.local/share/local-deep-research"|"/tmp")
- echo "Refusing to --reset LDR_DATA_DIR='$LDR_DATA_DIR' -> '$real' (looks unsafe)." >&2
- exit 1
- ;;
- esac
- echo "Resetting test data dir: $real"
- rm -rf -- "$real"
-fi
-
-mkdir -p "$LDR_DATA_DIR"
-echo "Using LDR_DATA_DIR=$LDR_DATA_DIR"
-
-exec "$(dirname "$0")/$restart"
diff --git a/tests/api_tests_with_login/README.md b/tests/api_tests_with_login/README.md
index 6b6f9964a5..b489ba2a96 100644
--- a/tests/api_tests_with_login/README.md
+++ b/tests/api_tests_with_login/README.md
@@ -184,7 +184,7 @@ npm run test:debug
1. **View server logs**:
```bash
- tail -f /tmp/ldr_server.log
+ tail -f /tmp/ldr_server_5000.log
```
2. **Check test cookies**: