diff --git a/LOCAL.md b/LOCAL.md index cdae1c1..e1f5b6c 100644 --- a/LOCAL.md +++ b/LOCAL.md @@ -23,8 +23,7 @@ macOS so it can use the Apple GPU. ```bash cd Netra -git submodule update --init --recursive # be/ and fe/ -scripts/local.sh setup # checks, .env with generated passwords, Ollama + model +scripts/local.sh setup # checks, be/ and fe/, .env with generated passwords, Ollama + model scripts/local.sh up # builds and starts everything (first build: a few minutes) scripts/local.sh awake # keep the Mac awake for schedules and robots ``` @@ -175,13 +174,14 @@ reach NETRA directly. | Command | | |---|---| +| `git pull` then `scripts/local.sh up` | update: `up` moves `be/` and `fe/` to the commits the pull brought, then rebuilds what changed | | `scripts/local.sh up` | start or update (rebuilds changed images) | | `scripts/local.sh start` | start the images built before, without internet (demo day) | | `scripts/local.sh status` | containers and API health | | `scripts/local.sh lan` | the Mac's address on every network, for `CC_URL` and phones | | `scripts/local.sh ports` | ports NETRA publishes and whether another program holds them | | `scripts/local.sh logs [api\|db\|caddy\|...]` | follow logs | -| `scripts/local.sh doctor` | check Docker, Ollama, model, AI link, LAN reachability, firewall, sleep | +| `scripts/local.sh doctor` | check Docker, `be/` and `fe/`, Ollama, model, AI link, LAN reachability, firewall, sleep | | `scripts/local.sh export [file]` | database, photos and floor plans in one file | | `scripts/local.sh import ` | replace all data here with an export (asks first) | | `scripts/local.sh down` | stop (data is kept) and allow sleep again | @@ -211,6 +211,9 @@ After editing `.env`: `scripts/local.sh up`. | Symptom | Fix | |---|---| +| `up` fails at `COPY be/go.mod` or `COPY fe/package.json`: not found | `be/` and `fe/` are empty: `git submodule update --init --recursive` (an older `local.sh` did not fetch them) | +| `be: building your checkout, not the commit NETRA records` | you work in that submodule, so `up` leaves it alone; `git submodule update -- be` builds the recorded commit | +| `API not healthy`, its log: `password authentication failed for user "netra"` | the database volume comes from an earlier install and keeps that install's password; `up` and `start` give it the password of `.env` now. With an older `local.sh`: `printf "ALTER USER netra PASSWORD '%s';\n" "$(grep '^POSTGRES_PASSWORD=' .env \| cut -d= -f2-)" \| docker compose exec -T db psql -X -q -U netra -d postgres`, then `docker compose restart api` | | `doctor`: containers cannot reach Ollama | `brew services stop ollama && OLLAMA_HOST=0.0.0.0 ollama serve` | | Robot stays offline | on the robot `curl http://
/healthz`; no answer: other network, venue Wi-Fi isolating devices, or the macOS firewall (allow Docker); `401` in `logs api`: wrong `CC_TOKEN` | | `port … is used by …` at `up` | another stack or program has the port: set `NETRA_LAN_PORT` / `NETRA_TUNNEL_PORT` ([Next to other stacks](#next-to-other-stacks)) | diff --git a/scripts/local.sh b/scripts/local.sh index 258ba41..0587d94 100755 --- a/scripts/local.sh +++ b/scripts/local.sh @@ -1,8 +1,8 @@ #!/usr/bin/env bash # NETRA Fleet on a Mac — robots connect over the same network (Wi-Fi, hotspot or cable). # -# scripts/local.sh setup check tools, create .env, start Ollama, pull the AI model -# scripts/local.sh up build and start the stack, print the addresses +# scripts/local.sh setup check tools, fetch be/ and fe/, create .env, pull the AI model +# scripts/local.sh up fetch be/ and fe/, build and start the stack, print the addresses # scripts/local.sh start start without rebuilding (no internet needed, demo day) # scripts/local.sh robot [name] register a robot and print its /etc/pashupati/pashupati.env # scripts/local.sh lan addresses robots and phones can use on each network @@ -180,6 +180,49 @@ awake_running() { need_env() { [[ -f $ENV_FILE ]] || die "no .env yet: run scripts/local.sh setup"; } +# "flag path" for every submodule: = at the commit NETRA records, + at another one, - not fetched, +# U with merge conflicts. +submodule_flags() { + git submodule status 2>/dev/null | + awk '{ flag = substr($0, 1, 1); split(substr($0, 2), f, " "); print (flag == " " ? "=" : flag), f[2] }' +} + +# A submodule nobody works in: no local changes, detached as git submodule update leaves it, and its +# commit on a remote branch. Moving it to the recorded commit then loses nothing. +submodule_pristine() { + [[ -z $(git -C "$1" status --porcelain 2>/dev/null) ]] || return 1 + git -C "$1" symbolic-ref -q HEAD >/dev/null && return 1 + [[ -n $(git -C "$1" branch -r --contains HEAD 2>/dev/null) ]] +} + +# The image is built from be/ (the service) and fe/ (the dashboard), both submodules. A clone without +# --recursive leaves them empty and a pull leaves them at the old commits: fetch them before a build. +# A submodule someone works in (changes, a branch, local commits) is built as it is. +need_sources() { + git rev-parse --git-dir >/dev/null 2>&1 || return 0 # a copy without git: built as it is + local flag path fetch='' keep='' + while read -r flag path; do + case $flag in + -) fetch="$fetch $path" ;; + +) if submodule_pristine "$path"; then fetch="$fetch $path"; else keep="$keep $path"; fi ;; + U) die "$path has merge conflicts: resolve them there first" ;; + esac + done < <(submodule_flags) + if [[ -n $fetch ]]; then + warn "fetching$fetch at the commits NETRA records" + # shellcheck disable=SC2086 # the paths are be and fe, word splitting wanted + git submodule update --init --recursive -- $fetch || + die "could not fetch$fetch: check the internet and GitHub over SSH (ssh -T git@github.com)" + fi + for path in $keep; do + warn "$path: building your checkout, not the commit NETRA records (git submodule update -- $path)" + done + for path in be fe; do + [[ -n $(ls -A "$path" 2>/dev/null) ]] || die "$path/ is empty: git submodule update --init" + done + ok "be $(git -C be rev-parse --short HEAD), fe $(git -C fe rev-parse --short HEAD)" +} + ollama_up() { curl -fsS --max-time 3 http://127.0.0.1:11434/api/tags >/dev/null 2>&1; } start_ollama() { @@ -212,6 +255,30 @@ wait_healthy() { return 1 } +# The API did not come up: show why before giving up. +api_failed() { + printf '\n%sLast lines of the API:%s\n' "$D" "$N" >&2 + docker compose logs --no-log-prefix --tail=12 api >&2 || true + die "API not healthy: scripts/local.sh logs api, scripts/local.sh doctor" +} + +# PostgreSQL keeps the password of the first start of its volume: a database from an earlier +# install (another .env, another checkout) refuses the password of this .env and the API never +# starts. The .env is the reference: give the database its password at every start (local socket, +# no password needed there). Quiet when the database is not up. +sync_db_password() { + local pw + pw=$(envget POSTGRES_PASSWORD) + [[ -n $pw ]] || return 0 + for _ in $(seq 60); do + docker compose exec -T db pg_isready -U netra -d netra >/dev/null 2>&1 && break + sleep 1 + done + printf "ALTER USER netra PASSWORD '%s';\n" "${pw//\'/\'\'}" | + docker compose exec -T db psql -X -q -v ON_ERROR_STOP=1 -U netra -d postgres >/dev/null 2>&1 || + warn "could not set the database password from .env (scripts/local.sh logs db)" +} + cmd_setup() { title "Tools" command -v docker >/dev/null || die "Docker Desktop is not installed: https://www.docker.com/products/docker-desktop/" @@ -226,6 +293,9 @@ cmd_setup() { fi ok "Ollama $(ollama --version 2>/dev/null | awk '{print $NF}')" + title "Sources" + need_sources + title "Configuration" local model if [[ $(ram_gb) -ge 16 ]]; then model=qwen2.5vl:7b; else model=qwen2.5vl:3b; fi @@ -262,9 +332,12 @@ cmd_up() { docker info >/dev/null 2>&1 || die "Docker Desktop is not running: open -a Docker" check_ports start_ollama || warn "Ollama is not running: final detection falls back to the robot result" + title "Sources" + need_sources title "Starting NETRA Fleet (first build takes a few minutes)" docker compose up -d --build --remove-orphans - wait_healthy || die "API not healthy: scripts/local.sh logs api" + sync_db_password + wait_healthy || api_failed cmd_addresses } @@ -276,7 +349,8 @@ cmd_start() { start_ollama || warn "Ollama is not running: final detection falls back to the robot result" title "Starting NETRA Fleet (no rebuild)" docker compose up -d --no-build --remove-orphans || die "images missing: run scripts/local.sh up once with internet" - wait_healthy || die "API not healthy: scripts/local.sh logs api" + sync_db_password + wait_healthy || api_failed cmd_addresses } @@ -501,6 +575,21 @@ cmd_doctor() { [[ $mem =~ ^[0-9]+$ ]] || mem=0 if [[ $((mem / 1073741824)) -ge 4 ]]; then ok "Docker memory $((mem / 1073741824)) GB"; else warn "Docker memory below 4 GB (Settings → Resources)"; fi + title "Sources" + if git rev-parse --git-dir >/dev/null 2>&1; then + local flag path + while read -r flag path; do + case $flag in + =) ok "$path at the commit NETRA records ($(git -C "$path" rev-parse --short HEAD))" ;; + +) warn "$path at another commit than NETRA records (up fetches it, unless you work there)" ;; + -) bad "$path/ not fetched (scripts/local.sh up fetches it)" ;; + *) bad "$path has merge conflicts" ;; + esac + done < <(submodule_flags) + else + ok "a copy without git: be/ and fe/ are built as they are" + fi + title "AI" if ollama_up; then ok "Ollama on the Mac"; else bad "Ollama not running (brew services start ollama)"; fi local model