Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions LOCAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down Expand Up @@ -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 <file>` | replace all data here with an export (asks first) |
| `scripts/local.sh down` | stop (data is kept) and allow sleep again |
Expand Down Expand Up @@ -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://<address>/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)) |
Expand Down
97 changes: 93 additions & 4 deletions scripts/local.sh
Original file line number Diff line number Diff line change
@@ -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 <id> [name] register a robot and print its /etc/pashupati/pashupati.env
# scripts/local.sh lan addresses robots and phones can use on each network
Expand Down Expand Up @@ -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() {
Expand Down Expand Up @@ -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/"
Expand All @@ -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
Expand Down Expand Up @@ -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
}

Expand All @@ -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
}

Expand Down Expand Up @@ -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
Expand Down
Loading