From 6534946bc7c8fc1ee5b85d96989f9cccb24fc832 Mon Sep 17 00:00:00 2001 From: Jack Kingsman Date: Mon, 30 Mar 2026 16:25:47 -0700 Subject: [PATCH] Simplify installation instructions --- README.md | 42 ++++++++++++++++-------------------------- README_ADVANCED.md | 25 ------------------------- 2 files changed, 16 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 29b9709..b6e3828 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,6 @@ Backend server + browser interface for MeshCore mesh radio networks. Connect you ![Screenshot of the application's web interface](app_screenshot.png) -## Disclaimer - -This is developed with very heavy agentic assistance -- there is no warranty of fitness for any purpose. It's been lovingly guided by an engineer with a passion for clean code and good tests, but it's still mostly LLM output, so you may find some bugs. - -If extending, have your LLM read the three `AGENTS.md` files: `./AGENTS.md`, `./frontend/AGENTS.md`, and `./app/AGENTS.md`. - ## Start Here Most users should choose one of these paths: @@ -95,30 +89,20 @@ Access the app at http://localhost:8000. Source checkouts expect a normal frontend build in `frontend/dist`. -On Linux, if you want this installed as a persistent `systemd` service that starts on boot and restarts automatically on failure, run `bash scripts/setup/install_service.sh` from the repo root. +> [!NOTE] +> Running on lightweight hardware/ don't want to build the frontend locally? From a cloned checkout, run `python3 scripts/setup/fetch_prebuilt_frontend.py` to fetch and unpack a prebuilt frontend into `frontend/prebuilt`, then start the app normally with `uv run uvicorn app.main:app --host 0.0.0.0 --port 8000`. -## Path 1.5: Use The Prebuilt Release Zip - -Release zips can be found as an asset within the [releases listed here](https://github.com/jkingsman/Remote-Terminal-for-MeshCore/releases). This can be beneficial on resource constrained systems that cannot cope with the RAM-hungry frontend build process. - -If you downloaded the release zip instead of cloning the repo, unpack it and run: - -```bash -cd Remote-Terminal-for-MeshCore -uv sync -uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 -``` - -The release bundle includes `frontend/prebuilt`, so it does not require a local frontend build. - -Alternatively, if you have already cloned the repo, you can fetch just the prebuilt frontend into your working tree without downloading the full release zip via `python3 scripts/setup/fetch_prebuilt_frontend.py`. +> [!TIP] +> On Linux, you can also install RemoteTerm as a persistent `systemd` service that starts on boot and restarts automatically on failure: +> +> ```bash +> bash scripts/setup/install_service.sh +> ``` +> +> For the full service workflow and post-install operations, see [README_ADVANCED.md](README_ADVANCED.md). ## Path 2: Docker -> **Warning:** Docker has had reports intermittent issues with serial event subscriptions. The native method above is more reliable. - -Local Docker builds are architecture-native by default. On Apple Silicon Macs and ARM64 Linux hosts such as Raspberry Pi, `docker compose build` / `docker compose up --build` will produce an ARM64 image unless you override the platform. - Edit `docker-compose.yaml` to set a serial device for passthrough, or uncomment your transport (serial or TCP). Then: ```bash @@ -212,3 +196,9 @@ If you enable Basic Auth, protect the app with HTTPS. HTTP Basic credentials are - Advanced setup, troubleshooting, HTTPS, systemd, remediation variables, and debug logging: [README_ADVANCED.md](README_ADVANCED.md) - Contributing, tests, linting, E2E notes, and important AGENTS files: [CONTRIBUTING.md](CONTRIBUTING.md) - Live API docs after the backend is running: http://localhost:8000/docs + +## Disclaimer + +This is developed with very heavy agentic assistance -- there is no warranty of fitness for any purpose. It's been lovingly guided by an engineer with a passion for clean code and good tests, but it's still mostly LLM output, so you may find some bugs. + +If extending, have your LLM read the three `AGENTS.md` files: `./AGENTS.md`, `./frontend/AGENTS.md`, and `./app/AGENTS.md`. diff --git a/README_ADVANCED.md b/README_ADVANCED.md index c61ed54..ff79af4 100644 --- a/README_ADVANCED.md +++ b/README_ADVANCED.md @@ -46,39 +46,14 @@ Accept the browser warning, or use [mkcert](https://github.com/FiloSottile/mkcer ## Systemd Service -Two paths are available depending on your comfort level with Linux system administration. - -### Simple install (recommended for most users) - On Linux systems, this is the recommended installation method if you want RemoteTerm set up as a persistent systemd service that starts automatically on boot and restarts automatically if it crashes. Run the installer script from the repo root. It runs as your current user, installs from wherever you cloned the repo, and prints a quick-reference cheatsheet when done — no separate service account or path juggling required. ```bash bash scripts/setup/install_service.sh ``` -The script interactively asks which transport to use (serial auto-detect, serial with explicit port, TCP, or BLE), whether to build the frontend locally or download a prebuilt copy, whether to enable the bot system, and whether to set up HTTP Basic Auth. It handles dependency installation (`uv sync`), validates `node`/`npm` for local builds, adds your user to the `dialout` group if needed, writes the systemd unit file, and enables the service. After installation, normal operations work without any `sudo -u` gymnastics: - You can also rerun the script later to change transport, bot, or auth settings. If the service is already running, the installer stops it, rewrites the unit file, reloads systemd, and starts it again with the new configuration. -```bash -# Update to latest and restart -cd /path/to/repo -git pull -uv sync -cd frontend && npm install && npm run build && cd .. -sudo systemctl restart remoteterm - -# Refresh prebuilt frontend only (skips local build) -python3 scripts/setup/fetch_prebuilt_frontend.py -sudo systemctl restart remoteterm - -# View live logs -sudo journalctl -u remoteterm -f - -# Service control -sudo systemctl start|stop|restart|status remoteterm -``` - ## Debug Logging And Bug Reports If you're experiencing issues or opening a bug report, please start the backend with debug logging enabled. Debug mode provides a much more detailed breakdown of radio communication, packet processing, and other internal operations, which makes it significantly easier to diagnose problems.