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.

12.2 KB
Raw Blame
#!/bin/bash
# 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.
#
# The server makes itself non-dumpable at startup, so on Linux a same-user
# `fuser PORT/tcp`, `lsof -i` or `ss -p` cannot see which process owns the
# port (its /proc fd entries become root-only). This script therefore
# starts the server in its own process group, records that group in
# ${XDG_RUNTIME_DIR:-/tmp}/ldr_server_PORT.pid, and on the next restart stops
# the group only after checking it is an LDR server launched for this PORT.
# It exits non-zero if the port is still taken or the new server fails to
# start listening.
#
# Referenced in:
#   - tests/api_tests_with_login/README.md
#   - examples/api_usage/http/README.md
#   - examples/api_usage/http/advanced/simple_http_example.py
# Do not delete without updating those references.

set -u
# No job control, even when invoked from `bash -i`, with `set -m`, or with
# monitor in an exported SHELLOPTS. With job control every background job
# leads its own process group, and util-linux setsid then forks instead of
# exec'ing, so $! would no longer be the server's process group.
set +m

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

SERVER_PATTERN="local_deep_research.web.app"
PID_DIR="${XDG_RUNTIME_DIR:-/tmp}"
[ -d "${PID_DIR}" ] || PID_DIR=/tmp
PID_FILE="${PID_DIR}/ldr_server_${PORT}.pid"
LOG_FILE="/tmp/ldr_server_${PORT}.log"
# Seconds to wait for the old server to exit and for the new one to listen.
STOP_TIMEOUT=15
START_TIMEOUT="${LDR_RESTART_START_TIMEOUT:-90}"
case "${START_TIMEOUT}" in
    ''|*[!0-9]*|0)
        echo "Error: LDR_RESTART_START_TIMEOUT must be a positive whole number of seconds, got '${START_TIMEOUT}'." >&2
        exit 2
        ;;
esac

# Probe host: LDR_WEB_HOST as the server will see it, without IPv6 brackets.
# A wildcard bind accepts connections on loopback. The host can also come
# from the web.host setting or a legacy server_config.json in the data dir;
# this script does not read those, so export LDR_WEB_HOST if you set the
# host there to something other than a wildcard or loopback address.
PROBE_HOST="${LDR_WEB_HOST:-127.0.0.1}"
PROBE_HOST="${PROBE_HOST#[}"
PROBE_HOST="${PROBE_HOST%]}"
case "${PROBE_HOST}" in
    0.0.0.0|'') PROBE_HOST=127.0.0.1 ;;
    ::) PROBE_HOST=::1 ;;
esac

# True when something accepts TCP connections on PORT. Uses bash's
# /dev/tcp, which needs no access to the listening process's /proc entries.
# Bounded by `timeout` where available, since a filtered address can make
# the connect hang.
port_in_use() {
    # $1/$2 expand in the child bash, which gets host and port as arguments.
    # shellcheck disable=SC2016
    local probe='exec 3<>"/dev/tcp/$1/$2"'
    if command -v timeout >/dev/null 2>&1; then
        timeout 2 bash -c "${probe}" _ "${PROBE_HOST}" "${PORT}" 2>/dev/null
    else
        bash -c "${probe}" _ "${PROBE_HOST}" "${PORT}" 2>/dev/null
    fi
}

# True while any process in process group $1 is alive.
group_alive() {
    kill -0 -- "-$1" 2>/dev/null
}

# True when the pidfile may be trusted: a regular file, not a symlink, and
# owned by the current user (a shared /tmp lets others pre-create it).
pid_file_trusted() {
    [ -f "${PID_FILE}" ] && [ ! -L "${PID_FILE}" ] && [ -O "${PID_FILE}" ]
}

# True when some process in group $1 was launched for this PORT. The
# server itself is non-dumpable, so its environ is root-only, but the
# `pdm run` / `env` processes above it in the group stay readable.
group_serves_port() {
    local pid
    for pid in $(pgrep -g "$1" 2>/dev/null); do
        if tr '\0' '\n' 2>/dev/null < "/proc/${pid}/environ" \
            | grep -qxF "LDR_WEB_PORT=${PORT}"; then
            return 0
        fi
    done
    return 1
}

# Stop the server this script launched for PORT, by the process group
# recorded in PID_FILE. Nothing is signalled unless the group runs
# SERVER_PATTERN and was launched with LDR_WEB_PORT=PORT, so a stale or
# planted pidfile cannot stop another port's server or an unrelated group.
stop_recorded_server() {
    local pgid
    [ -e "${PID_FILE}" ] || [ -L "${PID_FILE}" ] || return 0
    if ! pid_file_trusted; then
        echo "Warning: ignoring ${PID_FILE}: not a regular file owned by $(id -un)." >&2
        return 0
    fi
    pgid=$(cat "${PID_FILE}" 2>/dev/null)
    case "${pgid}" in
        ''|*[!0-9]*) rm -f "${PID_FILE}"; return 0 ;;
    esac
    if [ "${pgid}" -le 1 ]; then
        rm -f "${PID_FILE}"
        return 0
    fi
    if ! pgrep -g "${pgid}" -f "${SERVER_PATTERN}" >/dev/null 2>&1; then
        rm -f "${PID_FILE}"
        return 0
    fi
    if ! group_serves_port "${pgid}"; then
        echo "Warning: process group ${pgid} in ${PID_FILE} is not an LDR server for port ${PORT}; not stopping it." >&2
        rm -f "${PID_FILE}"
        return 0
    fi
    echo "Stopping LDR server process group ${pgid} on port ${PORT}..."
    kill -TERM -- "-${pgid}" 2>/dev/null
    local i
    for ((i = 0; i < STOP_TIMEOUT; i++)); do
        group_alive "${pgid}" || break
        sleep 1
    done
    if group_alive "${pgid}"; then
        echo "Server did not exit after ${STOP_TIMEOUT}s; sending SIGKILL." >&2
        kill -KILL -- "-${pgid}" 2>/dev/null
        sleep 1
    fi
    rm -f "${PID_FILE}"
}

# Record process group $1 in PID_FILE without following a planted symlink
# or overwriting a file another user owns.
write_pid_file() {
    if [ -L "${PID_FILE}" ] || { [ -e "${PID_FILE}" ] && ! pid_file_trusted; }; then
        echo "Warning: not recording PID in ${PID_FILE}: not a regular file owned by $(id -un)." >&2
        return 1
    fi
    rm -f "${PID_FILE}"
    (set -C; echo "$1" > "${PID_FILE}") 2>/dev/null || {
        echo "Warning: could not write ${PID_FILE}." >&2
        return 1
    }
}

echo "Stopping existing LDR server on port ${PORT} (if any)..."
stop_recorded_server

# A server this script did not start (or one started before it recorded
# PIDs) is not in PID_FILE. Try a port-scoped stop; on Linux this only
# finds a non-dumpable LDR server when run as root.
if port_in_use; then
    if command -v fuser >/dev/null 2>&1; then
        fuser -k "${PORT}/tcp" >/dev/null 2>&1
    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
        fi
    fi
    for ((i = 0; i < STOP_TIMEOUT; i++)); do
        port_in_use || break
        sleep 1
    done
fi

if port_in_use; then
    echo "Error: port ${PORT} is still in use; not starting a new server." >&2
    echo "It is held by a process this script did not start, and on Linux a" >&2
    echo "running LDR server is non-dumpable, so same-user fuser/lsof cannot" >&2
    echo "see it. Find and stop it with one of:" >&2
    echo "  pgrep -af '${SERVER_PATTERN}|ldr-web'   # then: kill <PID>" >&2
    echo "  sudo fuser -k ${PORT}/tcp" >&2
    echo "or pass a different PORT." >&2
    exit 1
fi
echo "Port ${PORT} is free."

# Change to the project root.
cd "$(dirname "$0")/../.." || exit 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

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 launcher PID, not a transient subshell that has
# already exited. nohup ignores SIGHUP, so the server survives the launcher
# exiting and is reparented to init. setsid (where available) puts the
# server and its `pdm run` parent in a new process group. Because job
# control is off (`set +m` above), the background job does not lead a
# group, so setsid exec's in place and the new group's ID is $!; this is
# checked once the server is up, before the next restart relies on it.
launcher=(nohup)
if command -v setsid >/dev/null 2>&1; then
    launcher+=(setsid)
fi
"${launcher[@]}" env "${env_args[@]}" pdm run python -m local_deep_research.web.app > "${LOG_FILE}" 2>&1 &
SERVER_PID=$!
if [ "${#launcher[@]}" -gt 1 ]; then
    write_pid_file "${SERVER_PID}"
fi

# Wait until the new server accepts connections; fail loudly if it exits
# first (e.g. the port was taken, or startup refused) or never listens.
started=0
for ((i = 0; i < START_TIMEOUT; i++)); do
    if ! kill -0 "${SERVER_PID}" 2>/dev/null; then
        break
    fi
    if port_in_use; then
        started=1
        break
    fi
    sleep 1
done

if [ "${started}" -ne 1 ]; then
    if kill -0 "${SERVER_PID}" 2>/dev/null; then
        echo "Error: server (PID ${SERVER_PID}) is not listening on port ${PORT} after ${START_TIMEOUT}s." >&2
        echo "It is still running; set LDR_RESTART_START_TIMEOUT to wait longer." >&2
    else
        echo "Error: server failed to start on port ${PORT}." >&2
        rm -f "${PID_FILE}"
    fi
    echo "--- last 40 lines of ${LOG_FILE} ---" >&2
    tail -40 "${LOG_FILE}" >&2 2>/dev/null
    exit 1
fi

# Confirm the recorded group really is $!; if setsid forked anyway, the
# pidfile would name a dead group, so drop it and say how to stop instead.
if pid_file_trusted; then
    pgid=$(ps -o pgid= -p "${SERVER_PID}" 2>/dev/null | tr -d ' ')
    if [ "${pgid}" != "${SERVER_PID}" ]; then
        echo "Warning: server is not in process group ${SERVER_PID}; next restart cannot stop it automatically." >&2
        rm -f "${PID_FILE}"
    fi
fi

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 view logs: tail -f ${LOG_FILE}"
if pid_file_trusted; then
    echo "To stop server: kill -TERM -- -${SERVER_PID}   (or rerun this script)"
else
    echo "To stop server: pkill -f '${SERVER_PATTERN}'   (stops every instance)"
fi

exit 0