# run/ — pick how Trakop runs

Trakop runs two ways from **this one folder of code**. There is no second copy of the
project: the same files run in containers or directly on this machine, and these three
scripts switch between them.

```bash
run/status.sh            # which mode am I in right now?
run/with-docker.sh       # switch to Docker
run/without-docker.sh    # switch to no Docker
```

Add `--dry-run` to either switch to see exactly what it would do without doing it.

---

## The two modes

|  | **without Docker** | **with Docker** |
|---|---|---|
| Serves `http://localhost` | host Apache + php7.4-fpm | the `trakop-cakephp` container |
| Database | host MySQL — **the same one in both** | host MySQL — the same one |
| Database client | `/adminer.php`, `/phpmyadmin` | `http://127.0.0.1:8082` |
| Realtime tracking `:8400` | `ops/trakop-node.service` | the `trakop-node` container |
| TrakopLens search | index inside the app's own MySQL | pgvector + Ollama (AI embeddings) |
| Needs | nothing beyond PHP + MySQL | ~7 GB of container images |

**The database is never containerised.** Your business data lives in host MySQL in both
modes, so switching mode never touches, moves or risks it.

---

## What actually differs for the assistant

Only how it *searches* its knowledge:

- **With Docker** an AI model reads your question and matches it by meaning.
- **Without Docker** it matches by important words instead. Same 159 tools, same 590
  help articles, same safety limits — and it is actually *better* at refusing to invent
  features it does not have.

Where it is weaker: a question worded completely differently from the help article that
answers it. See `ops/trakoplens-host-mode.md` for the measurements.

---

## Things worth knowing

**Both scripts ask for your password.** Swapping who owns port 80 means restarting
system services, which needs root. The scripts re-run themselves under `sudo` so you
only ever type one command.

**Nothing is deleted when you switch.** Stopping Docker keeps every container image and
both saved data volumes, so switching back takes seconds and rebuilds nothing.

**Only one mode at a time.** Both want port 80. The scripts hand it over properly rather
than letting the two fight.

**Keep both search indexes built.** On a machine used both ways, run:

```bash
code/tools/trakoplens/setup-host-rag.sh --all
```

The nightly rebuild already does this. If you only ever build the mode you happen to be
in, the *other* mode quietly answers from knowledge that stopped being updated — and
nothing on screen tells you.

**After switching to no-Docker, realtime tracking needs installing once:**

```bash
sudo cp ops/trakop-node.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now trakop-node
```

`run/without-docker.sh` reminds you if it is missing.

---

## If something looks wrong

`run/status.sh` probes rather than trusting configuration — it tells you which backend
actually answered, not which one is configured. Deeper detail:

- `code/tools/trakoplens/host_status.php` — per-backend readiness
- `code/tools/trakoplens/verify-host-mode.sh` — proves no-Docker end to end
- `docker/scripts/verify-stack.sh` — proves the container stack
- `ops/docker/MODES.md` — the full host-vs-Docker reference