From c2bfa97d302edc03ac07ccdbc360c96bbdca8ec7 Mon Sep 17 00:00:00 2001
From: larssand <larssand@LPW0JW6L1>
Date: Sun, 30 Aug 2026 22:04:49 +0200
Subject: [PATCH] update readme install

---
 README.md         | 261 +++++++++++++++++++++++++++++++++++++++++-----
 README.sv.md      | 261 +++++++++++++++++++++++++++++++++++++++++-----
 windows/README.md |  43 ++++++++
 3 files changed, 509 insertions(+), 56 deletions(-)

diff --git a/README.md b/README.md
index e98217a..f694f32 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,45 @@ RC RaceCore is an RC timing and race-control system with support for sponsor eve
 - Security and performance audit: `docs/security-performance-audit.md`
 - Swedish operational guide: `README.sv.md`
 
+## Windows Quick Start
+
+For a new Windows 11 computer, open **PowerShell** and follow these steps.
+
+1. Check whether Git is installed:
+
+```powershell
+git --version
+```
+
+2. If `git` is not recognized, install it and reopen PowerShell:
+
+```powershell
+winget install --id Git.Git --exact --source winget
+```
+
+3. Download RC RaceCore and enter the project directory:
+
+```powershell
+Set-Location $HOME
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+Set-Location .\Live_RC
+```
+
+4. Run the complete installer. It installs/checks Node.js, installs npm dependencies, verifies SQLite and starts the server in the background:
+
+```powershell
+.\windows\install.bat
+```
+
+5. Verify the server and open `http://localhost:8081`:
+
+```powershell
+npm.cmd run status
+Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"
+```
+
+If `winget` is missing, install [Git for Windows](https://git-scm.com/download/win). You can also download the repository as a ZIP without Git. See the complete [Installation](#installation) section for ZIP installation, LAN access, updates and troubleshooting.
+
 ## Screenshots
 
 Current layouts for race operation, live presentation, training and system configuration. Click an image to open the full-resolution version.
@@ -413,46 +452,212 @@ Example:
 - Retain the current system voice and passing beep as offline fallbacks.
 - Support uploaded or prerecorded WAV/MP3 clips for fixed start and finish announcements.
 
-## Windows installation
-Use 64-bit Windows 11 and Node.js 22 or 24 LTS. The easiest supported setup is:
+## Installation
 
-1. Clone or extract the complete repository, preferably to `C:\\Live_RC`.
-2. Double-click `windows\\install.bat`.
-3. The installer runs `npm.cmd restart` and leaves the backend running.
-4. Open `http://localhost:8081`.
+RC RaceCore runs on 64-bit Windows 11 and Linux. Use Node.js 22 or 24 LTS and npm 10 or newer. The repository includes `package-lock.json`, so use `npm ci` rather than `npm install` for repeatable installations.
 
-The setup script can install Node.js LTS through `winget`, runs locked dependency installation with `npm.cmd ci`, verifies SQLite/Express, and checks the bundled AMMC runtime. Full instructions and troubleshooting: [`windows/README.md`](windows/README.md).
+### Windows 11 - new computer
+
+#### 1. Install Git
+
+Open PowerShell and check whether Git is available:
+
+```powershell
+git --version
+```
+
+If Windows reports that `git` is not recognized, install Git with Windows Package Manager:
+
+```powershell
+winget install --id Git.Git --exact --source winget
+```
+
+Close and reopen PowerShell after installation, then run `git --version` again. If `winget` is unavailable, install Git for Windows from [git-scm.com](https://git-scm.com/download/win).
+
+#### 2. Download RC RaceCore
+
+Clone the public repository from a normal PowerShell prompt:
+
+```powershell
+Set-Location $HOME
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+Set-Location .\Live_RC
+```
+
+Enter the raw URL exactly as shown. Do not paste Markdown syntax such as `[https://...](https://...)` into PowerShell.
+
+If you do not want to install Git, open [the public repository](https://git.dio.nu/Public/Live_RC), download its ZIP archive, and extract the complete archive. Make sure `package.json`, `server.js`, `src\`, and `windows\` are all in the same project directory.
+
+#### 3. Run the Windows installer
+
+From the project directory:
+
+```powershell
+.\windows\install.bat
+```
+
+You can also double-click `windows\install.bat` in Explorer. The installer:
+
+- installs Node.js LTS through `winget` when Node is missing or unsupported
+- installs/checks the Microsoft Visual C++ runtime used by AMMC
+- runs `npm.cmd ci` using the locked dependency versions
+- verifies Express, SQLite, and bundled AMMC files
+- creates `data\` and `logs\`
+- runs `npm.cmd restart` and leaves RC RaceCore running in the background
+
+If the installer cannot install Node automatically, install Node.js 22 or 24 LTS from [nodejs.org](https://nodejs.org/en/download), reopen PowerShell, and run the installer again.
+
+#### 4. Verify and open the application
+
+```powershell
+npm.cmd run status
+Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"
+```
+
+Open:
+
+```text
+http://localhost:8081
+```
+
+To open RC RaceCore from another computer on the race LAN, run `ipconfig` on the server and use:
+
+```text
+http://<windows-server-ip>:8081
+```
+
+Use `npm.cmd` in PowerShell. This bypasses the common `npm.ps1 cannot be loaded because running scripts is disabled` error. Plain `npm` normally works in Command Prompt.
+
+#### Windows manual installation
+
+If you do not use `install.bat`:
+
+```powershell
+node --version
+npm.cmd --version
+npm.cmd ci
+npm.cmd run verify
+npm.cmd start
+```
+
+Do not use `npm.cmd ci --ignore-scripts`. The native SQLite dependency needs its install script.
+
+### Linux - Ubuntu/Debian
+
+#### 1. Install Git and basic tools
+
+```bash
+sudo apt update
+sudo apt install -y git curl build-essential
+git --version
+```
+
+#### 2. Install Node.js 22 LTS when needed
+
+Check the installed version:
+
+```bash
+node --version
+npm --version
+```
+
+If Node is missing or older than version 22, install Node.js 22 from NodeSource:
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+node --version
+npm --version
+```
+
+Node.js 22 or 24 LTS is recommended. Node.js 18 and 20 are not supported by the current native SQLite dependency.
+
+#### 3. Clone, install, and start
+
+```bash
+mkdir -p ~/git
+cd ~/git
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+cd Live_RC
+npm ci
+npm run verify
+chmod +x AMMC/linux_x86-64/ammc-amb
+npm start
+npm run status
+curl http://127.0.0.1:8081/api/health
+```
+
+`npm start` launches RC RaceCore in the background. Open `http://localhost:8081`, or find the Linux server address with `hostname -I` and open `http://<linux-server-ip>:8081` from another computer.
+
+If the bundled Linux AMMC binary reports a missing `GLIBC` version, use an AMMC build compatible with the host distribution. Do not manually replace the operating system's glibc.
+
+### Runtime commands
+
+Windows PowerShell:
 
-Common commands:
 ```powershell
 npm.cmd start
-npm.cmd stop
-npm.cmd restart
 npm.cmd run status
+npm.cmd restart
+npm.cmd stop
 npm.cmd run start:fg
 ```
 
-- `npm.cmd start` starts the backend in the background
-- `npm.cmd stop` stops the process via `data/server.pid`
-- `npm.cmd restart` restarts the backend
-- `npm.cmd run status` shows whether the backend is running
-- `npm.cmd run start:fg` runs in foreground for troubleshooting
+Linux:
 
-### Windows scripts
-The `windows/` folder includes:
-- `windows\\install.bat` installs dependencies and runs `npm.cmd restart`
-- `windows\\start_ammc.bat` starts AMMC in the background
-- `windows\\start_backend.bat` starts `npm.cmd start` in the background
-- `windows\\restart_backend.bat` runs `npm.cmd restart` after updates
-- `windows\\start_all.bat` starts both AMMC + backend and opens the web page
-- `windows\\stop_all.bat` stops the managed backend and `ammc-amb.exe`
+```bash
+npm start
+npm run status
+npm restart
+npm stop
+npm run start:fg
+```
 
-Backend logs:
-- `logs\\server.out.log`
-- `logs\\server.err.log`
+- `start` runs the backend in the background
+- `status` reports whether the PID in `data/server.pid` is running
+- `restart` reloads backend changes
+- `stop` stops the managed process
+- `start:fg` runs in the current terminal and displays startup errors directly
+- stdout is written to `logs/server.out.log`
+- stderr is written to `logs/server.err.log`
+- SQLite data is stored in `data/rc_timing.sqlite`
 
-SQLite database file:
-- `data\\rc_timing.sqlite`
+### Windows helper scripts
+
+- `windows\install.bat`: install dependencies, verify, and restart
+- `windows\start_backend.bat`: start the backend in the background
+- `windows\restart_backend.bat`: restart after copied or pulled updates
+- `windows\start_ammc.bat`: start bundled AMMC manually
+- `windows\start_all.bat`: start AMMC and backend, then open the browser
+- `windows\stop_all.bat`: stop the backend and `ammc-amb.exe`
+
+### Update an existing installation without losing data
+
+The SQLite database and local configuration are in `data/`. Do not delete or replace this directory during an update.
+
+Windows:
+
+```powershell
+npm.cmd stop
+git pull --ff-only
+npm.cmd ci
+npm.cmd run verify
+npm.cmd restart
+npm.cmd run status
+```
+
+Linux:
+
+```bash
+npm stop
+git pull --ff-only
+npm ci
+npm run verify
+npm restart
+npm run status
+```
+
+If the installation came from a ZIP archive instead of Git, back up `data/`, extract the new application files, restore/retain the existing `data/` directory, run `npm ci`, and restart. Never copy `node_modules/` between Windows and Linux.
 
 ## Connect to AMMC
 There are two supported modes.
diff --git a/README.sv.md b/README.sv.md
index 513e348..55fd758 100644
--- a/README.sv.md
+++ b/README.sv.md
@@ -8,6 +8,45 @@ RC timing app med sponsor-eventflöde (delade bilar/transpondrar mellan olika he
 - Säkerhets- och prestandaaudit: `docs/security-performance-audit.md`
 - Primär engelsk README: `README.md`
 
+## Snabbinstallation På Windows 11
+
+Öppna **PowerShell** på den nya Windows-datorn och följ stegen nedan.
+
+1. Kontrollera om Git är installerat:
+
+```powershell
+git --version
+```
+
+2. Om `git` inte känns igen installerar du det och öppnar sedan PowerShell på nytt:
+
+```powershell
+winget install --id Git.Git --exact --source winget
+```
+
+3. Hämta RC RaceCore och gå till projektmappen:
+
+```powershell
+Set-Location $HOME
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+Set-Location .\Live_RC
+```
+
+4. Kör hela installationen. Den installerar/kontrollerar Node.js, installerar npm-dependencies, verifierar SQLite och startar servern i bakgrunden:
+
+```powershell
+.\windows\install.bat
+```
+
+5. Kontrollera servern och öppna `http://localhost:8081`:
+
+```powershell
+npm.cmd run status
+Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"
+```
+
+Om `winget` saknas installerar du [Git för Windows](https://git-scm.com/download/win). Repot kan även hämtas som ZIP utan Git. Se den kompletta delen [Installation](#installation) för ZIP-installation, LAN-åtkomst, uppdateringar och felsökning.
+
 ## Skärmbilder
 
 Aktuella layouter för racedrift, livevisning, träning och systemkonfiguration. Klicka på en bild för att öppna den i full upplösning.
@@ -402,46 +441,212 @@ Praktiskt exempel:
 - Nuvarande systemröst och passing-blipp behålls som offline-fallback.
 - Uppladdade eller förinspelade WAV/MP3-filer kan användas för fasta start- och målmeddelanden.
 
-## Windows installation
-Använd 64-bitars Windows 11 och Node.js 22 eller 24 LTS. Enklaste installationen är:
+## Installation
 
-1. Klona eller packa upp hela repot, helst till `C:\\Live_RC`.
-2. Dubbelklicka på `windows\\install.bat`.
-3. Installationen kör `npm.cmd restart` och lämnar backend igång.
-4. Öppna `http://localhost:8081`.
+RC RaceCore körs på 64-bitars Windows 11 och Linux. Använd Node.js 22 eller 24 LTS och npm 10 eller senare. Repot innehåller `package-lock.json`, så använd `npm ci` i stället för `npm install` för en reproducerbar installation.
 
-Installationsskriptet kan installera Node.js LTS med `winget`, kör en låst dependency-installation med `npm.cmd ci`, verifierar SQLite/Express och kontrollerar bundlad AMMC. Komplett guide och felsökning: [`windows/README.md`](windows/README.md).
+### Windows 11 - ny dator
+
+#### 1. Installera Git
+
+Öppna PowerShell och kontrollera om Git finns:
+
+```powershell
+git --version
+```
+
+Om Windows svarar att `git` inte känns igen installerar du Git med Windows Package Manager:
+
+```powershell
+winget install --id Git.Git --exact --source winget
+```
+
+Stäng och öppna PowerShell efter installationen och kör sedan `git --version` igen. Om `winget` saknas kan Git för Windows installeras från [git-scm.com](https://git-scm.com/download/win).
+
+#### 2. Hämta RC RaceCore
+
+Klona det publika repot från ett vanligt PowerShell-fönster:
+
+```powershell
+Set-Location $HOME
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+Set-Location .\Live_RC
+```
+
+Skriv den rena URL:en exakt som ovan. Klistra inte in Markdown-format som `[https://...](https://...)` i PowerShell.
+
+Om du inte vill installera Git öppnar du [det publika repot](https://git.dio.nu/Public/Live_RC), laddar ner ZIP-arkivet och packar upp hela arkivet. Kontrollera att `package.json`, `server.js`, `src\` och `windows\` ligger i samma projektmapp.
+
+#### 3. Kör Windows-installationen
+
+Från projektmappen:
+
+```powershell
+.\windows\install.bat
+```
+
+Du kan även dubbelklicka på `windows\install.bat` i Utforskaren. Installationen:
+
+- installerar Node.js LTS via `winget` om Node saknas eller har fel version
+- installerar/kontrollerar Microsoft Visual C++ Runtime som AMMC använder
+- kör `npm.cmd ci` med låsta dependency-versioner
+- verifierar Express, SQLite och bundlade AMMC-filer
+- skapar `data\` och `logs\`
+- kör `npm.cmd restart` och lämnar RC RaceCore igång i bakgrunden
+
+Om installationen inte kan installera Node automatiskt installerar du Node.js 22 eller 24 LTS från [nodejs.org](https://nodejs.org/en/download), öppnar PowerShell igen och kör installationen på nytt.
+
+#### 4. Verifiera och öppna sidan
+
+```powershell
+npm.cmd run status
+Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"
+```
+
+Öppna:
+
+```text
+http://localhost:8081
+```
+
+För att öppna RC RaceCore från en annan dator på race-nätverket kör du `ipconfig` på servern och använder:
+
+```text
+http://<windows-server-ip>:8081
+```
+
+Använd `npm.cmd` i PowerShell. Det undviker det vanliga felet `npm.ps1 cannot be loaded because running scripts is disabled`. Vanliga `npm` fungerar normalt i Kommandotolken.
+
+#### Manuell Windows-installation
+
+Om du inte använder `install.bat`:
+
+```powershell
+node --version
+npm.cmd --version
+npm.cmd ci
+npm.cmd run verify
+npm.cmd start
+```
+
+Använd inte `npm.cmd ci --ignore-scripts`. Den inbyggda SQLite-modulen behöver sitt installationsskript.
+
+### Linux - Ubuntu/Debian
+
+#### 1. Installera Git och grundverktyg
+
+```bash
+sudo apt update
+sudo apt install -y git curl build-essential
+git --version
+```
+
+#### 2. Installera Node.js 22 LTS vid behov
+
+Kontrollera installerad version:
+
+```bash
+node --version
+npm --version
+```
+
+Om Node saknas eller är äldre än version 22 installerar du Node.js 22 via NodeSource:
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt install -y nodejs
+node --version
+npm --version
+```
+
+Node.js 22 eller 24 LTS rekommenderas. Node.js 18 och 20 stöds inte av nuvarande native SQLite-dependency.
+
+#### 3. Klona, installera och starta
+
+```bash
+mkdir -p ~/git
+cd ~/git
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+cd Live_RC
+npm ci
+npm run verify
+chmod +x AMMC/linux_x86-64/ammc-amb
+npm start
+npm run status
+curl http://127.0.0.1:8081/api/health
+```
+
+`npm start` kör RC RaceCore i bakgrunden. Öppna `http://localhost:8081`, eller hitta Linux-serverns adress med `hostname -I` och öppna `http://<linux-server-ip>:8081` från en annan dator.
+
+Om den bundlade Linux-versionen av AMMC rapporterar att en `GLIBC`-version saknas behöver du en AMMC-binär som är byggd för hostens Linuxdistribution. Byt inte operativsystemets glibc manuellt.
+
+### Driftkommandon
+
+Windows PowerShell:
 
-Vanliga kommandon:
 ```powershell
 npm.cmd start
-npm.cmd stop
-npm.cmd restart
 npm.cmd run status
+npm.cmd restart
+npm.cmd stop
 npm.cmd run start:fg
 ```
 
-- `npm.cmd start` startar RC RaceCore i bakgrunden
-- `npm.cmd stop` stoppar processen via `data/server.pid`
-- `npm.cmd restart` startar om backend
-- `npm.cmd run status` visar om backend kör
-- `npm.cmd run start:fg` kör i foreground för felsökning
+Linux:
 
-### Windows scripts (bakgrundsstart)
-Det finns färdiga `.bat`-filer i mappen `windows/`:
-- `windows\\install.bat` installerar dependencies och kör `npm.cmd restart`
-- `windows\\start_ammc.bat` startar AMMC i bakgrunden
-- `windows\\start_backend.bat` startar `npm.cmd start` i bakgrunden
-- `windows\\restart_backend.bat` kör `npm.cmd restart` efter uppdateringar
-- `windows\\start_all.bat` startar både AMMC + backend och öppnar webbsidan
-- `windows\\stop_all.bat` stoppar den hanterade backendprocessen och `ammc-amb.exe`
+```bash
+npm start
+npm run status
+npm restart
+npm stop
+npm run start:fg
+```
 
-Backendloggar:
-- `logs\\server.out.log`
-- `logs\\server.err.log`
+- `start` kör backend i bakgrunden
+- `status` visar om PID-filen i `data/server.pid` motsvarar en aktiv process
+- `restart` laddar om ändringar i backend
+- `stop` stoppar den hanterade processen
+- `start:fg` kör i terminalen och visar startfel direkt
+- stdout skrivs till `logs/server.out.log`
+- stderr skrivs till `logs/server.err.log`
+- SQLite-data lagras i `data/rc_timing.sqlite`
 
-SQLite-filen skapas automatiskt här:
-- `data\\rc_timing.sqlite`
+### Windows hjälpskript
+
+- `windows\install.bat`: installerar dependencies, verifierar och startar om
+- `windows\start_backend.bat`: startar backend i bakgrunden
+- `windows\restart_backend.bat`: startar om efter kopierad eller hämtad uppdatering
+- `windows\start_ammc.bat`: startar bundlad AMMC manuellt
+- `windows\start_all.bat`: startar AMMC och backend samt öppnar webbläsaren
+- `windows\stop_all.bat`: stoppar backend och `ammc-amb.exe`
+
+### Uppdatera utan att förlora data
+
+SQLite-databasen och lokal konfiguration ligger i `data/`. Radera eller ersätt aldrig den katalogen vid en uppdatering.
+
+Windows:
+
+```powershell
+npm.cmd stop
+git pull --ff-only
+npm.cmd ci
+npm.cmd run verify
+npm.cmd restart
+npm.cmd run status
+```
+
+Linux:
+
+```bash
+npm stop
+git pull --ff-only
+npm ci
+npm run verify
+npm restart
+npm run status
+```
+
+Om installationen kommer från ett ZIP-arkiv i stället för Git säkerhetskopierar du `data/`, packar upp de nya programfilerna, återställer/behåller befintlig `data/`, kör `npm ci` och startar om. Kopiera aldrig `node_modules/` mellan Windows och Linux.
 
 ## Koppla mot AMMC
 Det finns nu två sätt:
diff --git a/windows/README.md b/windows/README.md
index f814e9c..8f13c04 100644
--- a/windows/README.md
+++ b/windows/README.md
@@ -2,6 +2,25 @@
 
 This folder contains the supported Windows 11 installation and start scripts for RC RaceCore.
 
+For a completely new computer, the shortest supported path is:
+
+```powershell
+winget install --id Git.Git --exact --source winget
+```
+
+Reopen PowerShell, then run:
+
+```powershell
+Set-Location $HOME
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+Set-Location .\Live_RC
+.\windows\install.bat
+npm.cmd run status
+Invoke-RestMethod -Uri "http://127.0.0.1:8081/api/health"
+```
+
+Open `http://localhost:8081` when the health check returns `ok = True`. The sections below explain missing Git, ZIP installation, Node.js, firewall rules and troubleshooting.
+
 ## Supported runtime
 
 - 64-bit Windows 11 (`x64` or `arm64`)
@@ -11,6 +30,30 @@ This folder contains the supported Windows 11 installation and start scripts for
 
 Node.js 18 and 20 are not supported by the current native SQLite dependency.
 
+## Get the project files
+
+Git is needed only when you want to clone and later update with `git pull`. Check it in PowerShell:
+
+```powershell
+git --version
+```
+
+If Git is missing:
+
+```powershell
+winget install --id Git.Git --exact --source winget
+```
+
+Reopen PowerShell, then clone the raw URL without Markdown brackets:
+
+```powershell
+Set-Location $HOME
+git clone https://git.dio.nu/Public/Live_RC.git Live_RC
+Set-Location .\Live_RC
+```
+
+Without Git, download the ZIP archive from [the public repository](https://git.dio.nu/Public/Live_RC) and extract the complete project. The project root must directly contain `package.json`, `server.js`, `src\`, and `windows\`.
+
 ## Recommended installation
 
 1. Extract or clone the complete repository, preferably to a short path such as `C:\Live_RC`.