# StarWatcher 0.8.73 — installation and sharing

## English

This bundle installs the StarWatcher server on a Raspberry Pi. Friends can open
its interface in a browser on Windows, macOS, Linux, iPhone or Android; the client
does not need a desktop app. The existing macOS `.app` in the development workspace
is an older build and is not this release.

1. Install Raspberry Pi OS Lite **64-bit**, Bookworm or Trixie, using Raspberry Pi
   Imager. Set a unique login, hostname (for example `starwatcher`), Wi-Fi if needed,
   timezone and SSH access. Connect the Pi and an RTSP/ONVIF camera to the same LAN.
2. Copy `StarWatcher-0.8.73-Pi.tar.gz` to the Pi. Extract and install:

   ```sh
   tar -xzf StarWatcher-0.8.73-Pi.tar.gz
   cd StarWatcher-0.8.73-Pi
   sha256sum -c SHA256SUMS
   bash scripts/install-rpi.sh --no-tailscale
   ```

   Internet is required for OS/Python dependencies and astronomy indexes. The
   bundle includes the local ONNX model and its separate license. Use `--no-vision`
   to omit installation of the optional model runtime. Use `--with-indi` only if
   mount/INDI hardware is needed. Tailscale is optional, belongs to the recipient's
   own account and must never reuse the sender's credentials.
3. Open `http://PI-IP:8787` (or `http://starwatcher.local:8787` if that hostname was
   configured and mDNS works). Choose English, Deutsch or فارسی at the top. Save
   unfinished form changes before switching language because the page reloads.
4. Configure **the recipient's own** camera account and stream, test the image,
   set the actual observing coordinates, and open the prominent monitoring card.
   A new camera/location needs its own star calibration and timing validation.
5. For remote control obtain the private token on the Pi:

   ```sh
   sudo cat /etc/starwatcher/starwatcher.env
   ```

   Enter only the `STARWATCHER_API_TOKEN` value into the dashboard token field.
   Keep the file private. Use the local network or a private VPN, not public port
   forwarding. The installer creates a new random token on a fresh installation.
6. Click **Start monitoring** when ready. This persists monitoring autostart.
   **Stop monitoring** persists the stopped state. systemd starts the service on
   boot independently of whether monitoring is enabled:

   ```sh
   systemctl is-enabled starwatcher
   systemctl status starwatcher --no-pager
   journalctl -u starwatcher -n 60 --no-pager
   ```

The share bundle contains code, generic settings, deployment units and model files.
It excludes personal credentials, live calibration, recordings, database/history,
private update commands and prior installation backups. It is an online installer,
not a bootable OS image. Installation on a fresh Pi and physical Pi 5 operation
still need hardware acceptance; browser/unit tests alone do not prove those.

### Raspberry Pi 5

The code uses Python, FFmpeg, IP-camera RTSP/ONVIF and systemd; the installer supports
64-bit Linux and Python 3.11+. The same architecture is intended for Pi 4 and Pi 5,
without changing tracking or identification algorithms. Native Python dependencies
must install successfully on the chosen OS release. Do not assume faster hardware
proves higher sustainable analysis FPS: test reception, recording, queue latency and
thermal throttling under the actual camera workload. Raspberry Pi recommends a 27 W
USB-C supply for Pi 5; active cooling is appropriate for sustained processing.

### A custom Pi OS image

Yes. Build from a **clean 64-bit base**, not a clone of a personal Pi. Raspberry Pi's
`rpi-image-gen` supports customized images; `pi-gen` builds Raspberry Pi OS images.
The image can include Python dependencies, FFmpeg, astronomy indexes, model files,
service user, directory permissions, time synchronization, generic configuration
and an enabled `starwatcher.service`.

A first-boot setup must create unique machine/SSH identity and API token and collect
network, camera credentials, location and notification details. Never bake the
sender's Wi-Fi, Tailscale identity, passwords, tokens, recordings or calibration into
a public image. Monitoring should remain off until that setup is complete; then
Start monitoring enables persistence after reboot. Test a flashed SD/SSD on Pi 4
and Pi 5, including reboot, network outage, camera reconnect and low disk space.

Official references:
- https://www.raspberrypi.com/documentation/computers/raspberry-pi.html
- https://github.com/raspberrypi/rpi-image-gen
- https://github.com/RPi-Distro/pi-gen

## Deutsch

Das Paket installiert den StarWatcher-Server auf einem Raspberry Pi. Die Oberfläche
läuft auf PCs und Mobilgeräten im Browser; eine Desktop-App ist nicht erforderlich.

1. Raspberry Pi OS Lite **64 Bit** (Bookworm oder Trixie) mit Imager installieren.
   Eigene Zugangsdaten, Hostname, Netzwerk, Zeitzone und SSH einrichten.
2. Das Paket auf den Pi kopieren und die oben angegebenen Befehle ausführen:
   entpacken, `sha256sum -c SHA256SUMS`, dann
   `bash scripts/install-rpi.sh --no-tailscale`.
3. `http://PI-IP:8787` öffnen und oben **Deutsch** wählen. Vor einem Sprachwechsel
   ungespeicherte Formulare speichern. Eigene RTSP-Kamera einrichten und testen,
   Beobachtungsstandort angeben und die hervorgehobene Überwachungskarte öffnen.
4. Das private Steuerungstoken steht auf dem Pi in
   `/etc/starwatcher/starwatcher.env`. Für Fernzugriff ein eigenes privates VPN
   verwenden. Die Installation benötigt Internet und erstellt ein eigenes Token.
5. **Überwachung starten** aktiviert den automatischen Wiederanlauf nach Neustart;
   **Überwachung stoppen** lässt sie auch nach Neustart gestoppt. Der systemd-Dienst
   selbst startet unabhängig davon automatisch.

Pi 5 nutzt dieselbe Architektur. Die Installation der nativen Abhängigkeiten und der
reale Kamerabetrieb müssen auf der Zielhardware geprüft werden; 27-W-Netzteil und
geeignete Kühlung einplanen. Ein eigenes OS-Image ist möglich. Es muss auf einer
sauberen Basis aufgebaut werden und beim ersten Start individuelle Zugangsdaten,
Token, Kamera und Standort erhalten. Dieses Paket ist noch kein bootfähiges Image.

## فارسی

این بسته برای نصب سرور روی Pi است؛ دوستان رابط برنامه را با مرورگر کامپیوتر یا
موبایل باز می‌کنند و به اپ جداگانه نیاز ندارند. فایل macOS قدیمیِ پوشهٔ توسعه،
نسخهٔ تازه نیست و نباید به‌جای این بسته ارسال شود.

۱. با Raspberry Pi Imager، نسخهٔ Lite و ۶۴ بیتی Raspberry Pi OS را نصب کنند و
نام کاربری، شبکه، منطقهٔ زمانی و SSH اختصاصی خودشان را تنظیم کنند.

۲. بسته را به Pi بفرستند و دستورهای بخش انگلیسی را اجرا کنند: استخراج، بررسی
SHA256SUMS و نصب با `bash scripts/install-rpi.sh --no-tailscale`.
این نصب برای دریافت وابستگی‌ها و داده‌های نجومی به اینترنت نیاز دارد.

۳. نشانی `http://PI-IP:8787` را باز کنند، زبان را انتخاب کنند، دوربین خودشان را
تنظیم و آزمایش کنند و مختصات واقعی محل را وارد کنند. پیش از تغییر زبان، فرم‌های
ذخیره‌نشده را ذخیره کنند. کالیبراسیون دستگاه شما برای محل و دوربین دیگری مناسب نیست.

۴. توکن کنترل از فایل `/etc/starwatcher/starwatcher.env` روی همان Pi خوانده می‌شود.
از حساب و توکن شبکهٔ خصوصی خودشان استفاده کنند. بستهٔ اشتراکی رمز یا اطلاعات
دستگاه شما را ندارد.

۵. «شروع پایش» ادامهٔ خودکار پایش پس از ریبوت را فعال می‌کند؛ «توقف پایش» آن را
خاموش نگه می‌دارد. سرویس اصلی برنامه در هر دو حالت با سیستم‌عامل بالا می‌آید.

برای Pi 5 تغییر بنیادی الگوریتم لازم نیست، اما نصب وابستگی‌ها و سرعت واقعی کار
باید روی سخت‌افزار آزمایش شود. ساخت Pi-OS اختصاصی ممکن است؛ پایه باید سیستم‌عامل
خام باشد و اطلاعات خصوصی هر کاربر در اولین راه‌اندازی وارد شود. این بسته نصاب
است و فایل بوت‌پذیر سیستم‌عامل نیست.